Set up AutoPromote end to end

How AutoPromote works

Your CI uploads a build to the store as it does today, then makes one HTTP call to AutoPromote. From there AutoPromote moves the build through each testing stage, waits a soak period between stages, watches store reviews, and rolls it out to production. You can pause, approve, skip a soak or halt at any point from the console.

Soak lengths, which stages run, and whether production needs a human approval are set per app. Every stage change can be sent to Slack, Microsoft Teams, PagerDuty or your own webhook.

What you need

• An app that is already published (or set up as a draft) in Google Play Console or App Store Connect.
• Admin access to that store account, to create an API key for AutoPromote.
• A CI pipeline that uploads builds (GitHub Actions, GitLab CI, Bitrise, fastlane, Xcode Cloud or anything that can run curl).

Create your workspace

1. Create an account with your work email. You become the owner of a new workspace.
2. Open Settings & Profile → Billing, choose how many apps you want to monitor and subscribe. Pro costs $8 per app per month or $36 per app per year, and each app includes two team seats. An Android app and an iOS app count as two apps.
3. Invite teammates from Team & Access. They receive an email with a link to join your workspace. See Team and roles for what each role can do.

Connect a Google Play app

AutoPromote talks to Google Play with a service account that you create and control. You can revoke it at any time from Play Console.

Create the service account

1. In Google Cloud Console, open (or create) a project and enable the Google Play Android Developer API. To use crash-rate checks, also enable the Google Play Developer Reporting API.
2. Go to IAM & Admin → Service accounts, create a service account (no Cloud roles are needed), then open it and add a key of type JSON. Your browser downloads the key file.
3. In Google Play Console, open Users and permissions → Invite new users and enter the service account's email address (it ends in iam.gserviceaccount.com).
4. Under App permissions, add your app and grant: Release apps to testing tracks, Release to production, exclude devices, and use Play App Signing, and View app information (read-only). Send the invitation.

Add the app in AutoPromote

1. In the console, open Onboard New App and choose Android (Google Play).
2. Enter the app name and the package name exactly as it appears in Play Console, for example com.yourcompany.app.
3. Upload the JSON key and press Validate. AutoPromote signs in as the service account and opens a test edit on your app; nothing is changed.
4. Choose your stages and soak times (see Release policy), then finish. The last step shows your app's ingestion token once; copy it into your CI secrets.

Connect an App Store app

AutoPromote uses an App Store Connect API key to distribute builds in TestFlight, submit them for review and control the release.

Create the API key

1. In App Store Connect, open Users and Access → Integrations → App Store Connect API → Team Keys. Only the Account Holder or an Admin can do this.
2. Generate a key with the App Manager role.
3. Download the .p8 file. Apple lets you download it only once, so store it safely.
4. Note the Key ID shown next to the key and the Issuer ID shown above the key list.

Prepare TestFlight

• Create at least one external testing group for the app, and fill in the Beta App Description and feedback email under TestFlight → Test Information. Apple requires both before Beta App Review.
• Declare export compliance: set ITSAppUsesNonExemptEncryption to NO in Info.plist if your app only uses standard encryption, or turn on Auto-declare no non-exempt encryption when onboarding. Builds without this declaration pause until it is answered.

Add the app in AutoPromote

1. Open Onboard New App and choose iOS (App Store).
2. Enter the app name and its bundle ID, for example com.yourcompany.app. An iOS app may share its identifier with your Android app; they are tracked separately.
3. Paste the Issuer ID and Key ID, upload the .p8 file and press Validate. AutoPromote looks your app up on App Store Connect to confirm the key works.
4. Optionally limit which TestFlight groups receive builds, and add the "What to Test" text sent to testers. Finish and copy the ingestion token.

Release policy

Each app has its own policy. Edit it during onboarding or later from Applications → your app → Policies.

Apple has no near-real-time crash API, so iOS has no automatic crash threshold. Use Halt from monitoring to let Crashlytics, Sentry or Datadog stop an iOS release instead.

Trigger releases from CI

After your pipeline uploads a build, call the trigger endpoint with the app's ingestion token. Store the token as a CI secret named AUTOPROMOTE_TOKEN. You can reveal or rotate it later under Applications → your app → CI.

- name: Upload to Google Play internal track
  uses: r0adkll/upload-google-play@v1
  with:
    serviceAccountJsonPlainText: ${{ secrets.PLAY_SERVICE_ACCOUNT_JSON }}
    packageName: com.yourcompany.app
    releaseFiles: app/build/outputs/bundle/release/app-release.aab
    track: internal

- name: Start AutoPromote release
  run: |
    curl -fsS -X POST https://autopromote.knoje.com/api/releases/trigger \
      -H "Authorization: Bearer ${{ secrets.AUTOPROMOTE_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d '{"packageName":"com.yourcompany.app","versionCode":${{ github.run_number }},"versionName":"${{ github.ref_name }}"}'

- name: Upload to App Store Connect
  run: |
    xcrun altool --upload-app -f build/App.ipa -t ios \
      --apiKey "$ASC_KEY_ID" --apiIssuer "$ASC_ISSUER_ID"

- name: Start AutoPromote release
  run: |
    curl -fsS -X POST https://autopromote.knoje.com/api/releases/trigger \
      -H "Authorization: Bearer ${{ secrets.AUTOPROMOTE_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d '{"platform":"ios","bundleId":"com.yourcompany.app","buildNumber":"${{ github.run_number }}","versionString":"1.4.0"}'

Other CI systems

Any system that can make an HTTPS request works. The call is the same; only the way you read secrets changes.

lane :release do
  upload_to_play_store(track: "internal")
  sh("curl", "-fsS", "-X", "POST", "https://autopromote.knoje.com/api/releases/trigger",
     "-H", "Authorization: Bearer #{ENV['AUTOPROMOTE_TOKEN']}",
     "-H", "Content-Type: application/json",
     "-d", { packageName: "com.yourcompany.app", versionCode: ENV["BUILD_NUMBER"].to_i }.to_json)
end

autopromote:
  stage: deploy
  script:
    - >
      curl -fsS -X POST https://autopromote.knoje.com/api/releases/trigger
      -H "Authorization: Bearer $AUTOPROMOTE_TOKEN"
      -H "Content-Type: application/json"
      -d "{\"packageName\":\"com.yourcompany.app\",\"versionCode\":$CI_PIPELINE_IID}"

Responses

Signed requests

Instead of sending the token in a header, you can sign the request with it. Send the current Unix time in X-AutoPromote-Timestamp and an HMAC-SHA256 of <timestamp>.<raw body> in X-AutoPromote-Signature. Signatures older than five minutes are rejected.

BODY='{"packageName":"com.yourcompany.app","versionCode":42}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$AUTOPROMOTE_TOKEN" -hex | sed 's/^.* //')
curl -fsS -X POST https://autopromote.knoje.com/api/releases/trigger \
  -H "Content-Type: application/json" \
  -H "X-AutoPromote-Timestamp: $TS" \
  -H "X-AutoPromote-Signature: sha256=$SIG" \
  -d "$BODY"

Alerts

Add channels under Notification Channels, choose which events each one receives, and press Test to send a sample message.

Events

Verify webhook signatures

Webhook deliveries carry the same X-AutoPromote-Timestamp and X-AutoPromote-Signature headers as signed CI requests, made with the channel's signing secret.

import crypto from 'node:crypto';

export function verifyAutoPromote(req, rawBody, secret) {
  const ts = req.headers['x-autopromote-timestamp'];
  const sig = (req.headers['x-autopromote-signature'] || '').replace('sha256=', '');
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  return sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Halt from monitoring

Point a crash or error alert at the halt-signal endpoint to stop a release automatically. It uses the same ingestion token as the trigger and works for both platforms.

curl -fsS -X POST https://autopromote.knoje.com/api/releases/halt-signal \
  -H "Authorization: Bearer $AUTOPROMOTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"platform":"ios","bundleId":"com.yourcompany.app","reason":"Crash-free sessions below 99%"}'

For Android, send "packageName" instead of "bundleId" and leave out platform. The endpoint returns 200 when it halted a release and 409 when nothing was in flight.

Run a release

The Releases page shows the active build on each stage, the current soak countdown and the event log. These actions are available while a release is in flight:

When a store review takes longer than expected (about four hours on Google Play, seven days on the App Store), AutoPromote pauses the release and sends a "Review pending" alert. If a review is rejected, fix the issue in the store console and press Resume; the same build is resubmitted.

What halt does

Team and roles

Removing someone signs them out everywhere immediately. A workspace always keeps at least one owner.

Billing

• Pro is billed per monitored app: $8 per app per month, or $36 per app per year. Each app includes two team seats.
• Change the number of apps from Settings & Profile → Billing. You can't go below the number of apps already connected.
• Manage billing opens the Polar customer portal for invoices, payment methods and cancellation. After cancelling, access continues until the end of the paid period.
• First-time subscribers can request a refund within 14 days; see the refund policy.

Troubleshooting

Validation says permission denied

Google Play: check the service account was invited to the right app with the release permissions listed above, and wait up to an hour for new permissions. App Store: the key needs the App Manager role and must belong to the team that owns the app.

The trigger returns 401

The token was rotated or copied incompletely. Reveal the current token under Applications → your app → CI and update the CI secret. For signed requests, check the server clock and that you sign the exact raw body.

The release is paused with "Review pending"

The store has not finished its review yet. Once the build is approved or live in the store console, press Resume.

An iOS release says "Missing export compliance"

Answer the encryption question for the build in App Store Connect, or set ITSAppUsesNonExemptEncryption in Info.plist, then press Resume.

An iOS build is ignored with 409

Its build number is not higher than the last one AutoPromote saw. Use increasing build numbers, or press Reset on the app before starting a new numbering scheme.

Still stuck? Email contact@knoje.com with your workspace email and the app's package name or bundle ID.

API reference

These endpoints use the app's ingestion token. Everything else is done from the console.