Skip to Content

GitHub Actions

Start a GitHub Actions workflow when a TestFlight build or your app status changes.

Point a Statused destination at a GitHub Actions workflow and Statused starts it for you: distribute a build to TestFlight the moment Apple finishes processing it, tag a release when your app is ready for distribution, or kick off anything else your pipeline already knows how to do. Your CI no longer has to sit idle for an hour waiting on Apple.

Statused starts your workflow through the Statused GitHub App, with a single workflow_dispatch input named statused_event that carries the details of what happened.

What the Statused GitHub App can access

You install the app on your personal account or organization and choose which repositories it can see. It asks for two permissions:

PermissionAccessWhy Statused needs it
ActionsRead and writeList your workflows and start the one you pick.
MetadataReadShow repository names and default branches in the setup.

The app doesn’t request access to your code, issues, or pull requests, and Statused doesn’t store a GitHub token. Each run is started with a short-lived token scoped to that one repository. When you connect, Statused only lists repositories you can push to.

Prerequisites

  • A GitHub repository on github.com where you can push. GitHub Enterprise Server isn’t supported.
  • Permission to install GitHub Apps on the account or organization that owns the repository, or an owner who can approve the request.
  • A Statused workflow that monitors the app you want to automate.

Setup

Add the statused_event input to your workflow

Add a workflow_dispatch trigger with a string input named statused_event to the workflow you want Statused to start:

.github/workflows/testflight.yml
on:
  workflow_dispatch:
    inputs:
      statused_event:
        description: "Event sent by Statused (JSON)"
        required: true
        type: string

Commit it to your default branch, and to the branch or tag the destination runs on (its ref) if that’s a different one. GitHub only lets apps start workflows whose file exists on the default branch, but it checks the trigger and inputs against the copy on the ref. The workflow can keep its other triggers, but any other workflow_dispatch input must be optional, because Statused only sends statused_event.

Connect GitHub

  1. In your dashboard, go to Destinations › Add Destination
  2. Select the GitHub Actions tab and click Connect GitHub
  3. On GitHub, pick the account or organization and choose All repositories or Only select repositories, then install

GitHub sends you back to Statused once the app is installed. If you can’t install apps on an organization, GitHub sends the request to its owners instead. Once they approve it, click Already installed? Link it on the GitHub Actions tab, or Refresh repositories if you’ve already connected an account. Use the same button when the app was installed directly on GitHub.

Create the destination

Choose the account, repository, and workflow. The ref is the branch or tag the workflow runs on and defaults to the repository’s default branch. Adjust the name if you like, and hit Add Destination to save it. You choose which events start a run in the Statused workflow, in the last step.

Send a test run

In your Destinations list, click the menu on the new destination and select Send Test Notification to start a real run of your workflow on the selected ref. The event has "test": true, so your workflow can skip the real work. Statused links you to the run when GitHub accepts it.

Choose the events in a workflow

Open or create a workflow under Workflows, pick your app, and select the new GitHub Actions destination. The destination starts a run for every build and app version status change that workflow notifies about.

To start a run only when a build is ready to distribute, use a workflow dedicated to it:

  1. Turn on Monitor TestFlight Builds
  2. Set Notify When Build Status Is to Valid
  3. Turn off Notify on app version status changes, so App Store review and release updates don’t start runs

The Destinations list shows the outcome of the latest run Statused started, with a link to it on GitHub.

Which events start a run

A GitHub Actions destination starts a run for every event the Statused workflows using it notify about, so each workflow’s filters decide what reaches your pipeline:

EventStarts a run whenEvent type
Build status changesA TestFlight build’s processing status changes to one that the workflow’s build status filter allows (all statuses when it’s empty). Requires Monitor TestFlight Builds.build.status.updated
App version status changesAn App Store or Google Play app version status changes to one that the workflow’s status filter allows. App Store workflows can turn these off with Notify on app version status changes.app.status.updated

Statused starts one run per build and status, even when several workflows share the destination. Other notifications, such as in-app events, pending agreements, and service status updates, never start a run.

The statused_event payload

statused_event is a JSON string. Parse it with fromJSON(inputs.statused_event) in expressions, or with jq in a shell step. A build event looks like this:

{
  "schema_version": 1,
  "id": "0b8f1c2e-5d4a-4c1e-9f7b-3a2d6e8c9b10",
  "type": "build.status.updated",
  "test": false,
  "occurred_at": "2026-11-17T14:32:05Z",
  "app": {
    "name": "Markdown Email",
    "bundle_id": "com.example.markdownemail",
    "apple_id": "1234567890",
    "platform": "ios"
  },
  "build": {
    "version": "1.2.0",
    "build_number": "345",
    "status": "VALID",
    "asc_build_id": "6f1a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8",
    "uploaded_at": "2026-11-17T13:58:41Z"
  },
  "message": "The status of build 1.2.0 (345) of Markdown Email changed to Valid."
}

An app status event has an app_version object instead of build:

"app_version": {
  "version": "1.2.0",
  "status": "READY_FOR_DISTRIBUTION",
  "status_label": "Ready for Distribution",
  "track": null
}
FieldDescription
schema_versionPayload format version, currently 1. New fields can be added without a version change.
idUnique ID of this event in Statused.
typebuild.status.updated, app.status.updated, or test.
testtrue for runs started with Send Test Notification. Skip anything with real consequences.
occurred_atWhen Statused detected the change (ISO 8601).
app.nameThe app’s name.
app.bundle_idBundle ID (iOS) or package name (Android).
app.apple_idThe app’s Apple ID in App Store Connect. null for Google Play apps and in test events.
app.platformios or android.
build.versionVersion string, such as 1.2.0. Only in build.status.updated events.
build.build_numberBuild number, as a string.
build.statusProcessing status in App Store Connect: PROCESSING, VALID, INVALID, or FAILED.
build.asc_build_idThe build’s ID in the App Store Connect API, so your workflow doesn’t need to look it up again.
build.uploaded_atWhen the build was uploaded (ISO 8601).
app_version.versionVersion string. Only in app.status.updated events.
app_version.statusRaw store status, such as READY_FOR_DISTRIBUTION or IN_REVIEW.
app_version.status_labelHuman-readable status, as shown in Statused notifications.
app_version.trackGoogle Play track, such as production. null for App Store apps.
messageThe same plain-text message Statused sends to your other destinations.

Read fields defensively: only the object that matches the event type is present. Test events never include build or app_version, and include app only when the destination is attached to a workflow.

Example: distribute to TestFlight when a build is Valid

This workflow sends every new iOS build to an external TestFlight group as soon as Apple finishes processing it. Pair it with a Statused workflow that notifies only about Valid builds and has app version notifications turned off, as in the last setup step. It runs on a Linux runner because distributing doesn’t need Xcode, which keeps it cheaper than a macOS job that waits for processing.

.github/workflows/testflight.yml
name: Distribute to TestFlight

on:
  workflow_dispatch:
    inputs:
      statused_event:
        description: "Event sent by Statused (JSON)"
        required: true
        type: string

# Runs for the same build never overlap.
concurrency:
  group: testflight-${{ fromJSON(inputs.statused_event).app.bundle_id }}-${{ fromJSON(inputs.statused_event).build.build_number }}
  cancel-in-progress: false

jobs:
  test-run:
    if: ${{ fromJSON(inputs.statused_event).test }}
    runs-on: ubuntu-latest
    steps:
      - name: Print the test event
        env:
          STATUSED_EVENT: ${{ inputs.statused_event }}
        run: echo "$STATUSED_EVENT" | jq .

  distribute:
    # Skip test events and anything that isn't an iOS build reaching Valid.
    if: >-
      ${{ !fromJSON(inputs.statused_event).test &&
      fromJSON(inputs.statused_event).type == 'build.status.updated' &&
      fromJSON(inputs.statused_event).build.status == 'VALID' &&
      fromJSON(inputs.statused_event).app.platform == 'ios' }}
    runs-on: ubuntu-latest
    timeout-minutes: 30
    env:
      APP_IDENTIFIER: ${{ fromJSON(inputs.statused_event).app.bundle_id }}
      APP_VERSION: ${{ fromJSON(inputs.statused_event).build.version }}
      BUILD_NUMBER: ${{ fromJSON(inputs.statused_event).build.build_number }}
    steps:
      - uses: actions/checkout@v7

      - uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true

      - name: Write the App Store Connect API key
        env:
          ASC_KEY_ID: ${{ secrets.ASC_KEY_ID }}
          ASC_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}
          ASC_PRIVATE_KEY: ${{ secrets.ASC_PRIVATE_KEY }}
        run: |
          jq -n \
            --arg key_id "$ASC_KEY_ID" \
            --arg issuer_id "$ASC_ISSUER_ID" \
            --arg key "$ASC_PRIVATE_KEY" \
            '{key_id: $key_id, issuer_id: $issuer_id, key: $key}' > "$RUNNER_TEMP/asc_api_key.json"

      - name: Distribute to external testers
        run: |
          bundle exec fastlane pilot distribute \
            --api_key_path "$RUNNER_TEMP/asc_api_key.json" \
            --app_identifier "$APP_IDENTIFIER" \
            --app_version "$APP_VERSION" \
            --build_number "$BUILD_NUMBER" \
            --distribute_external true \
            --groups "External Testers" \
            --changelog "Build $APP_VERSION ($BUILD_NUMBER)"

A few things worth knowing about this example:

  • It assumes your repository has a Gemfile with fastlane and a .ruby-version file, like most fastlane setups.
  • The distribute job checks the event type and build status itself, so it stays safe if the Statused workflow’s filters change later.
  • Event values reach the shell through env instead of ${{ }} inside run, which is GitHub’s recommended way to avoid script injection.
  • Replace External Testers with your TestFlight group name. fastlane submits the build for Beta App Review by default, which external groups require for the first build of each version.
  • External testing also needs the build’s export compliance answer. Set ITSAppUsesNonExemptEncryption in your Info.plist, or add --uses_non_exempt_encryption false if that’s accurate for your app.

Add these repository secrets under Settings › Secrets and variables › Actions:

SecretValue
ASC_KEY_IDKey ID of an App Store Connect API key with the App Manager or Admin role.
ASC_ISSUER_IDYour Issuer ID, from Users and Access › Integrations in App Store Connect.
ASC_PRIVATE_KEYThe full contents of the key’s .p8 file, including the BEGIN and END lines.

See Create an API Key if you need a new key. It can be the same key you use with Statused, as long as its role is App Manager or Admin.

Troubleshooting

When a run fails to start, the Destinations list shows GitHub’s reason next to the destination.

What you seeWhat to do
The Statused GitHub App was uninstalled or suspendedReinstall or unsuspend the app in your GitHub account or organization settings, then reconnect from the GitHub Actions tab. After a reinstall, destinations move to the new installation when it can access their repository.
GitHub couldn’t find the repository or workflow (404)Check that the repository still exists, the app still has access to it, and the workflow file wasn’t renamed or moved. A renamed workflow needs a new destination.
GitHub rejected the run (422)Make sure the workflow file on the destination’s ref has a workflow_dispatch trigger with a statused_event string input and that every other input is optional. The file must also exist on your default branch, and the ref must still exist.
GitHub is unavailable or rate limited the requestStatused retries automatically with backoff. It doesn’t retry errors that need a change on your side.
GitHub didn’t respond in timeThe run may or may not have started. Check the workflow’s run history on GitHub. Statused doesn’t retry, to avoid starting it twice.
A repository is missing from the listMake sure the app is installed with access to it and that you can push to it, then click Refresh repositories.
A workflow is missing from the listStatused only lists active workflows. Enable it under the repository’s Actions tab and make sure the file exists on the default branch.
No run started for an eventCheck that a Statused workflow using this destination notifies about it: Monitor TestFlight Builds is on for builds, the build status filter includes the status, and Notify on app version status changes is on for app versions. The first build Statused sees for an app never starts a run.

Limitations

  • A Valid build has finished processing, but that doesn’t make it available to external testers yet. They can install it only after export compliance is answered and, for the first build of a version, Beta App Review approves it.
  • Statused checks the most recent build of each app. If you upload a newer build before the previous one finishes processing, the older build may never start a run.
  • The first build Statused sees for an app is the baseline for later comparisons, so it doesn’t start a run.
  • Statused starts one run per build and status, but GitHub doesn’t guarantee idempotency when starting workflows, so a rare duplicate is possible. Use concurrency keyed on the build, as in the example, and make your steps safe to repeat.
  • The workflow file must exist on your default branch, even when the destination runs on another ref. The copy on that ref must also declare the statused_event input.
  • Statused lists up to 5,000 repositories per installation. For larger accounts, install the app on selected repositories instead of all of them.
  • Statused connects through its GitHub App only. Personal access tokens and deploy keys aren’t supported (deploy keys can’t call the GitHub API at all), and neither is GitHub Enterprise Server.

On this page