Oore CI
Build and shipDeliver builds

Publish to TestFlight and the App Store

Upload signed iOS builds to App Store Connect and follow them through TestFlight, review and phased release.

A build can upload its signed IPA to App Store Connect when it ends. Oore then sends the build to TestFlight groups or attaches it to an App Store version, and records each step as a release. Set it up in the pipeline, as below, and with a .oore.yaml version 2 file choose the destination and the signing identity per workflow; see Publish per workflow.

All App Store Connect calls leave from the Direct macOS runner and the daemon host. Allow outbound HTTPS to api.appstoreconnect.apple.com and Apple’s upload hosts.

What you need

  • App developer, maintainer, instance admin, or instance owner access.
  • iOS signing with an App Store Connect API key, as in Configure App Store Connect signing.
  • The app already exists in App Store Connect with the pipeline’s bundle ID.
  • For TestFlight, the names of the groups to distribute to.

1. Export for the App Store

  1. Open the pipeline and select Edit.
  2. Under Signing > iOS, set Distribution to App Store.
  3. Select Save changes.
  • In API or Hybrid mode, saving discards the stored profiles and syncs App Store distribution profiles from App Store Connect.
  • In Manual mode, upload an App Store distribution profile for each bundle ID. Oore rejects ad hoc or development profiles for this distribution.

Ad hoc and App Store profiles are not interchangeable, which is why changing the distribution replaces them. App Store IPAs cannot be installed from Oore. Testers install them through TestFlight.

2. Turn on publishing

  1. Open the pipeline’s Publishing tab.
  2. Under App Store Connect, check that the readiness list shows App Store distribution and App Store Connect API key as ready.
  3. Turn on Upload to App Store Connect after each successful build.
  4. For Destination, choose TestFlight or App Store.
    • For TestFlight, enter the TestFlight groups.
    • For the App Store, turn on Submit for review to submit the version once the build is attached. Then Phased release turns on Apple’s seven-day phased release, and Replace an open submission lets Oore cancel another open App Review submission for the app first. Apple allows one per app; with this off, the release is blocked until you cancel the other one.
    • Release after approval chooses When approved, When I release it (press Release now on the release) or On a date, with the date and time.
  5. Optional: under From the repository, Notes from the repository names a folder with one <locale>.txt file, or fastlane’s <locale>/release_notes.txt, per language. Those files become the notes of the version the build makes. Otherwise What to Test and What’s New come from the version’s release notes (see Release notes).
  6. Under Export compliance, turn on Uses non-exempt encryption only if the app uses encryption beyond what iOS provides, such as HTTPS.
  7. Select Turn on App Store publishing, or Save changes when publishing was already on.

For automation, set "export_method": "app_store" with PUT /v1/pipelines/{pipeline_id}/ios-signing, then send the publish settings with PUT /v1/pipelines/{pipeline_id}/publish/app-store:

{
  "enabled": true,
  "destination": "testflight",
  "testflight_groups": ["Internal QA"],
  "uses_non_exempt_encryption": false
}

For an App Store release, set "destination": "app_store", then submit_for_review, phased_release, release_type (after_approval, manual or scheduled), earliest_release_date and cancel_previous_submission as needed. release_notes_dir and preflight apply to both destinations. The settings’ release_notes list is no longer used for uploads: Oore reads it once to seed the notes of a project’s first version.

Release notes

Release notes belong to the app version, not the pipeline or one build. Every build of 2.5.1 sends the notes of 2.5.1: drafted from commits, written on the build page, or read from a CHANGELOG.md section that .oore.yaml names. TestFlight and the App Store get every language; Apple does not take “What’s New” on an app’s first version. See Release notes and changes.

Ready to submit?

The Run build drawer shows Ready to submit? for a pipeline or workflow that uploads to a store. The checklist lists what Apple or Google would refuse, such as unanswered age rating questions, each with a link to the page that fixes it, so it shows before a long build. The pipeline’s overview shows the same list, and oore pipeline readiness prints it.

TestFlight groups per workflow

To send one workflow’s builds to other testers, open the pipeline’s Workflows tab, select the workflow, and list the groups under TestFlight groups. They replace the groups the file and the pipeline’s settings name, for uploads to TestFlight only.

Oore warns on Home two weeks before the newest TestFlight build of a group reaches Apple’s 90 day limit, and again in its last three days, so testers are not left without the app.

What happens after a build

  1. The runner uploads the IPA with xcrun altool and the pipeline’s API key. The key is written to a private folder only for the upload.
  2. The release starts in processing while Apple processes the build. Oore sets the export compliance answer once the build is valid.
  3. TestFlight: Oore adds the build to the groups and sets “What to Test”. Internal groups complete at once. External groups go to beta review (in review) and complete when Apple approves.
  4. App Store: Oore finds or creates the version, attaches the build, sets “What’s New” and, if asked, submits it (in review). When the version is live the release follows the phased release (rolling at 1, 2, 5, 10, 20, 50 and 100 percent) until it is complete.

Pause, resume and complete on the release change Apple’s phased release. Apple sets the percentages, so raising a step is not available.

Store listing from the repository

To keep the description and keywords in Git, set Store listing from the repository in the pipeline’s App Store settings to a directory in fastlane’s layout, such as fastlane/metadata:

fastlane/metadata/
  en-US/
    description.txt       # at most 4000 characters
    keywords.txt          # at most 100 characters, comma separated
    promotional_text.txt  # at most 170 characters
    marketing_url.txt
    support_url.txt
    release_notes.txt     # read by "Notes from the repository"

The runner reads the files when it uploads the build, and Oore sets them on the version it submits, with “What’s New”. A file you leave out keeps what App Store Connect has, and review_information is skipped. A file over Apple’s limit fails the upload. If Apple refuses a field, the submission goes ahead and the release shows the refusal as a warning. Screenshots are not uploaded; change them in App Store Connect.

Pre-flight

Before the upload, the Publishing tab and the runner check what Apple would otherwise refuse after the upload:

  • the API key reaches App Store Connect and the app exists for the bundle ID;
  • the age rating and App Review contact details are filled in;
  • no other review submission is open, unless Replace an open submission is on;
  • the app icon has no transparency;
  • anything Apple refused on an earlier submission of this app, until a later submission goes through.

Pre-flight checks decides what a failure does. Automatic stops the upload once the app has had a release in review or live, and only warns before that. Stop the upload and Warn only fix the choice, and Off skips the checks. The same levels apply to Google Play, where Oore validates the edit before committing it. Read the checks from the API with GET /v1/pipelines/{pipeline_id}/publish/readiness.

Release states

A release shows where it is in the store, and what you need to do when the store is waiting on you:

StateMeaning
ProcessingApple is processing the upload.
BlockedThe store refused a step, or the version is ready but nobody submitted it. The release names the reason and links to App Store Connect.
In reviewApp Review or TestFlight beta review has the version.
ApprovedApp Review approved it and it waits for its release time, or for Release now.
RejectedApp Review rejected it. Read why in the Resolution Center, fix it, then Resubmit for review.
RollingLive, with a phased release in progress.
CompleteLive for everyone, or added to the TestFlight groups.

A blocked release says what is wrong in one sentence when Oore knows the refusal (age rating, “What’s New”, App Review contact details, export compliance, App Privacy, agreements, screenshots, a build number already used), with a button to the App Store Connect page that fixes it. The store’s own text is under Details from the store. A release in review says how long reviews usually take for the app, from its last five reviews.

A rejected release shows the reviewer’s message and the guidelines it names, with Reply in App Store Connect and Resubmit with a new build, which opens Run build for the same pipeline, branch and workflow.

A store refusal blocks the release at once and notifies once per reason (release_blocked). A network or server error blocks it only after an hour of failures. A blocked release leaves the state on its own once the store accepts the next check; Check again now checks at once.

The release menu offers what the store allows next: Release now, Resubmit for review, Pull from review and Check again now. Releases Oore was already following are read again with these states, and the release history notes the first change. Failed releases stay failed.

When the same version waits as Approved in both stores, the app’s Releases tab offers Release both under Versions, which releases each one now.

Releases made outside Oore

Every 15 minutes, and when you select Check stores on Home, Oore reads the App Store versions and Google Play tracks of every app a pipeline publishes. A release it did not make shows on Home and the Releases page marked Found in store, with no build, and on its own release page with when Oore found it and its version code. Oore follows it like its own, but never schedules rollout steps for a Play release it found; Manage rollout with Oore on the release attaches a schedule.

Verify the result

  • The build shows a succeeded Upload to App Store Connect step (publish-app-store).
  • The build’s Release tab shows the release moving through Processing to Complete for internal TestFlight groups, or to In review for external groups and App Store submissions.
  • App Store Connect shows the build in the TestFlight groups, or attached to the App Store version.

Publish per workflow

With a .oore.yaml version 2 file, an ad hoc test workflow and an App Store release workflow can run from one pipeline:

workflows:
  adhoc:
    signing: { ios: coin-adhoc } # ad hoc profiles; publishes nowhere
  release:
    signing: { ios: coin-app-store } # App Store profiles
    targets:
      ios:
        build: flutter build ipa --release
        publish:
          app_store: { destination: testflight, groups: [Internal QA] }
  • signing.ios names an iOS distribution identity in the app’s signing library. Its certificate and profiles replace the pipeline’s for that workflow, and the export follows its profiles. A workflow that uploads to App Store Connect needs an identity with App Store profiles; an ad hoc one refuses the build with invalid_signing.
  • publish.app_store sets the destination, groups, submit_for_review and phased_release, in place of the Publishing tab’s.
  • The upload still uses the pipeline’s App Store Connect API key, so keep the pipeline’s iOS signing on with Distribution set to App Store, and App Store Connect publishing turned on as in step 2. Release notes and the export compliance answer also come from the Publishing tab.
  • To stop one workflow’s uploads without a commit, open the pipeline’s Workflows tab, select Settings on the workflow, and turn Publishing off. iOS signing there can pick another identity.

oore pipeline validate --project "$PROJECT_ID" checks the identity names before you push, and oore pipeline plan prints each workflow’s identity, destination and export. Every field is in Publish and Signing.

Store health on Insights

After the first release, the daemon reads the app’s hang rate and launch time per version from App Store Connect power and performance metrics, using the App Store Connect key of the pipeline that made the newest release. Insights shows the latest version’s numbers for a typical user on all iPhones. They refresh every six hours, and Apple only reports them once enough users have run a version.

Troubleshooting

The Upload to App Store Connect step fails

Fix the cause, such as an expired API key, then retry the upload. The stored IPA is uploaded again without rebuilding or re-signing.

The release fails with “has no app with bundle ID”

Create the app in App Store Connect with the same bundle ID, then rebuild.

The upload fails with a bundle version error

Each upload needs a higher build number than the last one for that version. Bump the number after + in pubspec.yaml’s version in a commit, then run a new build. If the pipeline passes --build-number=$OORE_VERSION_CODE, raise Build number offset instead.

“What’s New” is not set

Apple does not accept “What’s New” on an app’s first version. The release history notes the skipped field and the release continues.

Next step

Promote builds between environments to send a tested TestFlight build to the App Store without rebuilding it.