Skip to content
eSHARS Operations

iOS TestFlight Promotion Flow

App: eSHARS Mobile (iOS) App Store Connect Apple ID: 6759011907 Bundle ID: com.authenticasolutions.eshars.mobile Related ticket: HM-8432

Overview

Builds progress through three stages before reaching end users:

GitHub Actions build
        │
        ▼
 Internal Testing  ──►  External Testing  ──►  App Store Submission
 (team only, no        (broader QA, requires    (public release,
  Apple review)         Apple beta review)       full App Review)

Each stage is managed in App Store Connect and uses TestFlight for pre-release distribution.

Stage 1 — Internal Testing

Who it’s for

Members of the App Store Connect team (developers, QA leads, PMs). Maximum 25 internal testers. No Apple review required — builds are available within minutes of upload.

How to add testers

  1. Go to App Store Connect → Users and Access.
  2. Invite the person with the Developer or App Manager role.
  3. Once added, go to TestFlight → Internal Testing → [group name] and add them to the group.

How builds reach internal testers

The Build iOS and Android GitHub Actions workflow uploads to TestFlight when Deploy iOS = true:

Trigger: workflow_dispatch (manual)
  └─ build-ios job
      └─ fastlane ios deploy_ios  →  TestFlight (internal groups auto-notified)

The workflow uses the App Store Connect API key (secret ASC_API_KEY_CONTENT) and skip_waiting_for_build_processing: true — builds appear in TestFlight once Apple finishes processing (typically 5–15 minutes after upload).

Tester experience

Testers install TestFlight from the App Store, accept the email invitation, and install the build from within the TestFlight app. New builds trigger a push notification automatically.

Stage 2 — External Testing

Who it’s for

Broader QA team, stakeholders, or pilot users outside the App Store Connect team. Up to 10,000 external testers. Requires Apple beta app review before the first external build of each new version can be distributed (typically 24–48 hours).

Setting up an external group

  1. In App Store Connect go to TestFlight → External Testing.
  2. Click + to create a new group (e.g. eSHARS QA).
  3. Add the build to the group — this triggers Apple’s beta review.
  4. Once approved, invite testers by email or share the public link.

Promoting from internal → external

You do not need to rebuild. Promote an already-uploaded internal build:

  1. In TestFlight → External Testing → [group], click Add Build.
  2. Select the internal build that passed internal testing.
  3. Submit for beta review (first time only for that version).
  4. Once Apple approves, external testers are notified.

Beta review notes

  • Apple reviews the app binary, not the TestFlight metadata.
  • A beta review rejection does not block internal testing.
  • Address any rejection feedback and re-submit the same build (no rebuild required if the binary is unchanged).

Stage 3 — App Store Submission

When to submit

After external testing confirms the build is stable and all acceptance criteria from the release checklist are met.

Submission steps

  1. Prepare the App Store listing in App Store Connect:

    • Version number matches the TestFlight build being promoted.
    • Release notes (What’s New) written.
    • Screenshots and metadata up to date.

  2. Select the build:

    • Go to App Store Connect → [App] → iOS App → [version].
    • Under Build, click + and select the TestFlight build.

  3. Submit for review:

    • Complete the export compliance, content rights, and advertising identifier questions.
    • Click Submit for Review.
    • Apple review typically takes 24–48 hours (can be faster).

  4. Release:

    • Manual release: you click Release This Version after approval.
    • Automatic release: set before submission — goes live immediately upon approval.

App Review rejection handling

  • Review the rejection reason in App Store Connect → Resolution Center.
  • Fix the issue, upload a new build via the workflow if needed, and re-submit.
  • Minor metadata fixes can be resolved without a new binary.

Build Versioning

Versions are calculated automatically from pubspec.yaml by the GitHub Actions workflow:

FieldSource
Version name (e.g. 1.2.4)pubspec.yaml version with PATCH auto-incremented
Build numberGITHUB_RUN_NUMBER (monotonically increasing)

Both are stamped into Info.plist at build time. App Store Connect uses the build number to distinguish builds with the same version name.

Tester Feedback

TestFlight includes a built-in feedback mechanism:

  • Testers can send screenshots with annotations and crash reports directly from the TestFlight app.
  • Feedback appears in App Store Connect → TestFlight → Feedback.
  • Crashes are aggregated under App Store Connect → Crashes.

For structured QA feedback, direct testers to the standard Jira intake process (HM board) using the Mobile_App_MVP label.

Quick Reference

ActionWhere
Trigger a build + deployGitHub Actions → Build iOS and Android → Run workflow
Add an internal testerApp Store Connect → Users and Access
Create/manage testing groupsApp Store Connect → TestFlight
Promote build to externalTestFlight → External Testing → Add Build
Submit for App Store reviewApp Store Connect → [App] → iOS App → Submit
View tester feedbackApp Store Connect → TestFlight → Feedback
  • HM-8432 — iOS: Configure TestFlight testing groups and add testers
  • eshars-mobile-ui/.github/workflows/build.yml — GitHub Actions build and deploy workflow
  • eshars-mobile-ui/fastlane/Fastfile — Fastlane deploy lanes (iOS: deploy_ios)