Aller au contenu

Ostorlab Integration with Appcircle

Overview

Ostorlab scans every successful Appcircle build automatically. Appcircle is a mobile CI/CD platform that builds, signs and distributes Android and iOS applications. When a build succeeds:

  1. Appcircle notifies Ostorlab through a webhook when a build finishes.
  2. Ostorlab downloads the build artifacts and extracts the application. If the build exports both an Android and an iOS application, Ostorlab starts a separate scan for each.
  3. Ostorlab starts a scan with the scan profile you chose and records what it did in a delivery history.

The integration works with Appcircle cloud and with self-hosted Appcircle installations.

Note

Fast Scan, Full Scan and Privacy Scan are supported. The other scan profiles are not supported yet.

Before You Start

  • An Ostorlab account with the permission to manage integrations.
  • An Appcircle account that can read the build profiles you want to scan.
  • A build workflow with the Export Build Artifacts step, so the APK, AAB or IPA is among the exported artifacts.
  • For iOS, a build profile with a signing identity. Without one, Appcircle exports an Xcode archive and no IPA, and Ostorlab has nothing to scan.

Create an Appcircle Personal Access Key

Ostorlab uses a personal access key to download the build artifacts from Appcircle.

  1. In Appcircle, click Organization in the left menu, then Security.
  2. Under Personal Access Key, generate a new key.

  3. Copy the key. Appcircle shows it only once.

    Personal access key in Appcircle

The key inherits the permissions of your user in the organization, so use an account that can read the build profiles you want to scan.

Create the Configuration in Ostorlab

  1. Open the menu, expand Library and go to Integrations. Pick the CI/CD & Apps category and select Appcircle.

    Integrations list with the Appcircle card

  2. Select Appcircle. The Documentation tab holds this guide, and the Configuration tab holds your configurations.

    Appcircle page

  3. Open the Configuration tab and click New configuration.

    Configurations table

  4. Fill in the form:

    New configuration dialog

    • Name: a name for the configuration.
    • Personal access key: the key copied from Appcircle. It is stored encrypted and never shown again.
    • Build profile: optional. Click Load profiles to pick one of your Appcircle build profiles, or paste a build profile ID. Leave it empty to scan every build that reaches the webhook.
    • Scan profile: Fast Scan, Full Scan or Privacy Scan.
    • UI Rules and Test Credentials: shown for the scan profiles that use them (not for Fast Scan). They are attached to every scan the configuration creates.
    • Self-hosted Appcircle: turn it on for a self-hosted installation and fill in the API base URL and the auth base URL, for example https://api.appcircle.example.com and https://auth.appcircle.example.com.

  5. Click Save.

Pick the Build Profile

Load profiles lists the build profiles the key can see, with their platform. If Appcircle refuses the key, the message tells you why.

Build profile picker

Pick UI Rules and Test Credentials

UI Rules and Test Credentials are not available for Fast Scan. They show up once you choose Full Scan or Privacy Scan, and each one opens a picker with a search box. Tick the ones to use and click a name to preview it.

UI rules picker

Add the Webhook in Appcircle

After saving, open the Webhook settings action of the configuration. It shows the Webhook URL and the Secret to paste in Appcircle. The secret is hidden until you click the eye icon.

Webhook settings

  1. In Appcircle, click Organization in the left menu, then Notifications and Webhooks.
  2. Click Add Webhook.
  3. Give the webhook a name and keep Enable on.
  4. Select the Build scope. The list of events appears.
  5. Turn on Build Successful. Turn on Build Complete with Warnings too if you want those builds scanned.
  6. Paste the Webhook URL from Ostorlab as the payload URL and the Secret as the secret.
  7. Save the webhook.

Add webhook in Appcircle

There is no build profile field in the Appcircle webhook: it sends every build of the organization. When the configuration has a build profile, Ostorlab skips the builds of the other profiles.

Ostorlab verifies the ac_signature header of every delivery with the secret and rejects deliveries older than ten minutes, as recommended by Appcircle.

Test the Connection

Open the actions menu of a configuration and click Test connection. Ostorlab checks that the configuration is saved and enabled, and that the key can list your build profiles. The dialog shows the result of each check and the build profiles the key can see. The profile used by the configuration is marked.

Connection test

Run a Build

Start a build in Appcircle. When it succeeds, a scan named after the configuration appears in your scans, with the scan profile, UI rules and test credentials of the configuration.

Follow the Deliveries

The History tab lists what Appcircle sent to each configuration and what Ostorlab did with it, newest first. Pick a configuration at the top, then click a delivery to see its details.

Delivery history

Each delivery has one of these outcomes:

Outcome Meaning
Scanned A scan was created. The details link to it.
Skipped Nothing to scan: the event is not a build, the build did not succeed, it belongs to another build profile, or it was already scanned.
Rejected The delivery was not accepted, for example a wrong signature or an old timestamp.
Error Ostorlab could not fetch or scan the build. The details give the reason.

Delivery details

If the build exports both an Android and an iOS application, each one is recorded as its own delivery and gets its own scan. If only one of them failed, a redelivery scans only that one.

Manage a Configuration

The actions menu of a configuration lets you edit it, enable or disable it, see its webhook settings, test the connection and delete it. A disabled configuration keeps its webhook but scans nothing. Deleting a configuration also deletes its delivery history, and the scans it created are kept.

Configuration actions

Troubleshooting

Message What to check
Appcircle rejected the personal access key The key was revoked or belongs to another organization. Generate a new key and edit the configuration.
The build artifacts hold no APK, AAB or IPA file Add the Export Build Artifacts step to the workflow and export the application.
The build produced an Xcode archive but no IPA The iOS build profile has no signing identity. Add one in Appcircle.
Bad or missing ac_signature The secret in the Appcircle webhook is not the one shown in Ostorlab. Paste it again.
A build is not scanned and the history shows nothing Check the Request History of the webhook in Appcircle, and that the webhook has the Build scope with Build Successful on.

Next Steps

Run your next build in Appcircle, then open the scan list in Ostorlab to check that the scan used the scan profile, UI rules and test credentials of the configuration.

  • See Scan profiles to choose the right profile for a build.
  • See the App Center guide for the same kind of integration with Microsoft App Center.