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:
| Permission | Access | Why Statused needs it |
|---|---|---|
| Actions | Read and write | List your workflows and start the one you pick. |
| Metadata | Read | Show 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:
on:
workflow_dispatch:
inputs:
statused_event:
description: "Event sent by Statused (JSON)"
required: true
type: stringCommit 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
- In your dashboard, go to Destinations › Add Destination
- Select the GitHub Actions tab and click Connect GitHub
- 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:
- Turn on Monitor TestFlight Builds
- Set Notify When Build Status Is to Valid
- 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:
| Event | Starts a run when | Event type |
|---|---|---|
| Build status changes | A 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 changes | An 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
}| Field | Description |
|---|---|
schema_version | Payload format version, currently 1. New fields can be added without a version change. |
id | Unique ID of this event in Statused. |
type | build.status.updated, app.status.updated, or test. |
test | true for runs started with Send Test Notification. Skip anything with real consequences. |
occurred_at | When Statused detected the change (ISO 8601). |
app.name | The app’s name. |
app.bundle_id | Bundle ID (iOS) or package name (Android). |
app.apple_id | The app’s Apple ID in App Store Connect. null for Google Play apps and in test events. |
app.platform | ios or android. |
build.version | Version string, such as 1.2.0. Only in build.status.updated events. |
build.build_number | Build number, as a string. |
build.status | Processing status in App Store Connect: PROCESSING, VALID, INVALID, or FAILED. |
build.asc_build_id | The build’s ID in the App Store Connect API, so your workflow doesn’t need to look it up again. |
build.uploaded_at | When the build was uploaded (ISO 8601). |
app_version.version | Version string. Only in app.status.updated events. |
app_version.status | Raw store status, such as READY_FOR_DISTRIBUTION or IN_REVIEW. |
app_version.status_label | Human-readable status, as shown in Statused notifications. |
app_version.track | Google Play track, such as production. null for App Store apps. |
message | The 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.
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
Gemfilewith fastlane and a.ruby-versionfile, like most fastlane setups. - The
distributejob 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
envinstead of${{ }}insiderun, which is GitHub’s recommended way to avoid script injection. - Replace
External Testerswith 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
ITSAppUsesNonExemptEncryptionin yourInfo.plist, or add--uses_non_exempt_encryption falseif that’s accurate for your app.
Add these repository secrets under Settings › Secrets and variables › Actions:
| Secret | Value |
|---|---|
ASC_KEY_ID | Key ID of an App Store Connect API key with the App Manager or Admin role. |
ASC_ISSUER_ID | Your Issuer ID, from Users and Access › Integrations in App Store Connect. |
ASC_PRIVATE_KEY | The 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 see | What to do |
|---|---|
| The Statused GitHub App was uninstalled or suspended | Reinstall 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 request | Statused retries automatically with backoff. It doesn’t retry errors that need a change on your side. |
| GitHub didn’t respond in time | The 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 list | Make 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 list | Statused 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 event | Check 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
concurrencykeyed 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_eventinput. - 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.
Related
- GitHub Docs —
workflow_dispatchevent - GitHub Docs — Security hardening: script injections
- fastlane —
upload_to_testflight(pilot) - Webhooks — for sending the same status data to your own HTTP endpoint or another CI system.