fix(mobile): separate TestFlight and store release versions (#20060)

Author: juliusmarminge

.github/workflows/mobile-eas-production.yml

@@ -6,25 +6,11 @@ name: Mobile EAS Production
 # fingerprint (platform-specific deps + pnpm version) and errors. On this Linux
 # runner, with corepack pinning pnpm 10.24 in eas.json, local == build.
 #
-# Every merge to main that touches the mobile app reconciles, per platform:
-#   1. Store builds: when no production build matches the current native
-#      fingerprint, or the latest build's version differs from app.config.ts,
-#      cut a new build and submit it (TestFlight + Play internal track). Native
-#      changes therefore ship a binary on merge, and bumping `version` is all
-#      it takes to start the next release train — the first build of a version enters
-#      external-TestFlight beta review immediately, and later builds of the
-#      same version auto-approve until that version is released. After App
-#      Store approval, Apple closes the release train and `version` must be
-#      bumped before another iOS build can be submitted. Releasing to the App
-#      Store stays a manual App Store Connect step.
-#   2. OTA: publish a production-channel update for each platform where at
-#      least one finished production build matches the current native
-#      fingerprint. Older binaries of the same major version with a matching
-#      fingerprint receive it too; the major version is part of the
-#      fingerprint (apps/mobile/fingerprint.config.js), so a new major never
-#      reaches the previous major's store binaries over the air. Until a
-#      build for the new fingerprint finishes, the OTA is skipped rather than
-#      published into the void.
+# Every merge reconciles native fingerprints and publishes matching OTAs.
+# iOS prereleases use the testflight profile (3.0.0); App Store binaries use
+# production and the committed app version, built manually. Both receive OTAs
+# for their own major version. Android continues using production automatically.
+# TestFlight beta review may still be required for subsequent builds.
 # Hold native-change PRs (the "📱 Native Change" label) and merge them as a
 # batch to avoid a store build per PR.
 # workflow_dispatch remains as a manual override for both modes (e.g. to
@@ -44,12 +30,13 @@ on:
           - build
           - update
       profile:
-        description: "Store build profile (v2-preview: TestFlight + Play closed track v2; build only)"
+        description: "production: store release; testflight: iOS 3.0.0 beta; v2-preview: legacy closed testing"
         required: true
         type: choice
         default: production
         options:
           - production
+          - testflight
           - v2-preview
       platform:
         description: "Target platform"
@@ -61,7 +48,7 @@ on:
           - android
           - all
       version:
-        description: "Optional build version override (blank uses app.config.ts; an override is committed before building)"
+        description: "Optional build version override (blank uses profile default; store overrides are committed)"
         required: false
         type: string
       message:
@@ -105,6 +92,17 @@ jobs:
           echo "::error::V2 previews use store builds only. Select mode=build."
           exit 1
 
+      - name: Validate TestFlight inputs
+        if: github.event_name == 'workflow_dispatch' && inputs.profile == 'testflight'
+        env:
+          PLATFORM: ${{ inputs.platform }}
+          VERSION: ${{ inputs.version }}
+        run: |
+          if [ "$PLATFORM" != "ios" ] || [ -n "$VERSION" ]; then
+            echo "::error::TestFlight uses platform=ios and its fixed version. Use production for a committed store version."
+            exit 1
+          fi
+
       - id: expo-token
         name: Check for EXPO_TOKEN
         env:
@@ -119,7 +117,7 @@ jobs:
 
       - id: version_app_token
         name: Mint release app token for version override
-        if: steps.expo-token.outputs.present == 'true' && github.event_name == 'workflow_dispatch' && inputs.mode == 'build' && inputs.version != ''
+        if: steps.expo-token.outputs.present == 'true' && github.event_name == 'workflow_dispatch' && inputs.mode == 'build' && inputs.version != '' && inputs.profile != 'testflight'
         uses: actions/create-github-app-token@v2
         with:
           app-id: ${{ secrets.RELEASE_APP_ID }}
@@ -204,10 +202,10 @@ jobs:
             const path = "apps/mobile/app.config.ts";
             const source = fs.readFileSync(path, "utf8");
             const next = source.replace(
-              /^(  version: ")[^"]+(".*)$/m,
+              /^(  version: repoEnv\.T3CODE_MOBILE_VERSION \?\? ")[^"]+(".*)$/m,
               `$1${process.env.RELEASE_VERSION}$2`,
             );
-            if (next === source && !source.includes(`  version: "${process.env.RELEASE_VERSION}"`)) {
+            if (next === source && !source.includes(`  version: repoEnv.T3CODE_MOBILE_VERSION ?? "${process.env.RELEASE_VERSION}"`)) {
               throw new Error("Could not update app version");
             }
             fs.writeFileSync(path, next);
@@ -234,6 +232,10 @@ jobs:
         env:
           MOBILE_BUILD_PROFILE: ${{ inputs.profile || 'production' }}
         run: |
+          if [ "$MOBILE_BUILD_PROFILE" = "testflight" ]; then
+            T3CODE_MOBILE_VERSION="$(node -p 'require("./eas.json").build.testflight.env.T3CODE_MOBILE_VERSION')"
+            export T3CODE_MOBILE_VERSION
+          fi
           version="$(npx expo config --json --type public | jq -r '.version')"
           {
             echo "## Manual $MOBILE_BUILD_PROFILE build"
@@ -257,23 +259,23 @@ jobs:
         working-directory: apps/mobile
         env:
           EXPO_TOKEN: ${{ secrets.EXPO_TOKEN }}
+          MOBILE_BUILD_PROFILE: ${{ inputs.profile || 'production' }}
+          OTA_MESSAGE: ${{ inputs.message || format('Production OTA ({0})', github.sha) }}
         run: |
+          if [ "$MOBILE_BUILD_PROFILE" = "testflight" ]; then
+            T3CODE_MOBILE_VERSION="$(node -p 'require("./eas.json").build.testflight.env.T3CODE_MOBILE_VERSION')"
+            export T3CODE_MOBILE_VERSION
+          fi
           eas update \
             --channel production \
             --environment production \
             --platform ${{ inputs.platform }} \
-            --message "${{ inputs.message || format('Production OTA ({0})', github.sha) }}" \
+            --message "$OTA_MESSAGE" \
             --non-interactive
 
-      # One pass per platform. The fingerprint decides OTA vs store build:
-      #   - a finished build matches → publish the OTA;
-      #   - a queued/in-progress build matches → wait, the next merge after it
-      #     finishes publishes the OTA (no duplicate build per merge);
-      #   - no build matches → native drift, so cut and submit a new build.
-      # A version bump also cuts a build even when native code is unchanged,
-      # because only the major version is part of the fingerprint.
-      # An errored build for this fingerprint is not retried on push (it would
-      # rebuild on every merge); retry via workflow_dispatch mode=build.
+      # Reconcile each version separately because the major is in the fingerprint.
+      # Production iOS only receives OTAs here; store binaries are manual releases.
+      # Failed prerelease builds are retried manually, not on every merge.
       - id: reconcile
         name: Publish OTA or cut store build
         if: steps.expo-token.outputs.present == 'true' && github.event_name == 'push'
@@ -282,17 +284,24 @@ jobs:
           EXPO_TOKEN: ${{ secrets.EXPO_TOKEN }}
         run: |
           failed=0
-          version="$(npx expo config --json --type public | jq -r '.version')"
           message="$(git log -1 --pretty=%s | head -c 120) ($(git rev-parse --short=9 HEAD))"
-          for platform in ios android; do
+          for target in ios:production ios:testflight android:production; do
+            platform="${target%%:*}"
+            profile="${target#*:}"
+            unset T3CODE_MOBILE_VERSION
+            if [ "$profile" = "testflight" ]; then
+              T3CODE_MOBILE_VERSION="$(node -p 'require("./eas.json").build.testflight.env.T3CODE_MOBILE_VERSION')"
+              export T3CODE_MOBILE_VERSION
+            fi
+            version="$(npx expo config --json --type public | jq -r '.version')"
             # eas-cli prints an environment-loaded notice to stdout before the
             # JSON even with --json, so discard everything before the document.
             hash="$(eas fingerprint:generate --platform "$platform" --environment production --json --non-interactive | sed -n '/^{/,$p' | jq -er '.hash | select(type == "string" and length > 0)')"
-            matches="$(eas build:list --platform "$platform" --build-profile production --fingerprint-hash "$hash" --limit 20 --json --non-interactive)"
+            matches="$(eas build:list --platform "$platform" --build-profile "$profile" --fingerprint-hash "$hash" --limit 20 --json --non-interactive)"
             finished="$(jq '[.[] | select(.status == "FINISHED")] | length' <<<"$matches")"
             active="$(jq '[.[] | select(.status == "NEW" or .status == "IN_QUEUE" or .status == "IN_PROGRESS")] | length' <<<"$matches")"
             errored="$(jq '[.[] | select(.status == "ERRORED")] | length' <<<"$matches")"
-            latest_version="$(eas build:list --platform "$platform" --build-profile production --limit 1 --json --non-interactive | jq -r '.[0].appVersion // "none"')"
+            latest_version="$(eas build:list --platform "$platform" --build-profile "$profile" --limit 1 --json --non-interactive | jq -r '.[0].appVersion // "none"')"
 
             if [ "$finished" -gt 0 ]; then
               if eas update \
@@ -301,34 +310,39 @@ jobs:
                 --platform "$platform" \
                 --message "$message" \
                 --non-interactive; then
-                echo ":white_check_mark: $platform: OTA published to production (fingerprint \`$hash\`)" >> "$GITHUB_STEP_SUMMARY"
+                echo ":white_check_mark: $platform/$profile: OTA published to production (fingerprint \`$hash\`)" >> "$GITHUB_STEP_SUMMARY"
               else
                 failed=1
-                echo ":x: $platform: OTA publish failed (fingerprint \`$hash\`)" >> "$GITHUB_STEP_SUMMARY"
+                echo ":x: $platform/$profile: OTA publish failed (fingerprint \`$hash\`)" >> "$GITHUB_STEP_SUMMARY"
               fi
             fi
 
+            # Never rebuild the released iOS version automatically.
+            if [ "$target" = "ios:production" ]; then
+              continue
+            fi
+
             reason=""
             if [ "$finished" -eq 0 ] && [ "$active" -eq 0 ]; then
               if [ "$errored" -gt 0 ]; then
-                echo ":x: $platform: the production build for fingerprint \`$hash\` errored — retry with workflow_dispatch mode=build" >> "$GITHUB_STEP_SUMMARY"
+                echo ":x: $platform/$profile: the build for fingerprint \`$hash\` errored — retry with workflow_dispatch mode=build profile=$profile platform=$platform" >> "$GITHUB_STEP_SUMMARY"
                 failed=1
                 continue
               fi
               reason="native fingerprint \`$hash\` has no build"
             elif [ "$latest_version" != "$version" ] && [ "$active" -eq 0 ]; then
-              reason="latest production build is $latest_version, app.config.ts says $version"
+              reason="latest $profile build is $latest_version, expected $version"
             fi
 
             if [ -z "$reason" ]; then
               if [ "$finished" -eq 0 ]; then
-                echo ":hourglass: $platform: production build for fingerprint \`$hash\` is in progress — OTA resumes on the next merge after it finishes" >> "$GITHUB_STEP_SUMMARY"
+                echo ":hourglass: $platform/$profile: build for fingerprint \`$hash\` is in progress — OTA resumes on the next merge after it finishes" >> "$GITHUB_STEP_SUMMARY"
               fi
               continue
             fi
 
             echo "$platform: $reason — building"
-            if eas build --platform "$platform" --profile production --auto-submit --non-interactive --no-wait; then
+            if eas build --platform "$platform" --profile "$profile" --auto-submit --non-interactive --no-wait; then
               echo ":building_construction: $platform: scheduled production build and submission for $version ($reason)" >> "$GITHUB_STEP_SUMMARY"
             else
               failed=1

apps/mobile/app.config.ts

@@ -229,7 +229,7 @@ const config: ExpoConfig = {
   slug: "t3-code",
   platforms: ["ios", "android"],
   scheme: variant.scheme,
-  version: "2.0.0",
+  version: repoEnv.T3CODE_MOBILE_VERSION ?? "2.0.0",
   runtimeVersion: {
     // Development manifests resolve on every launch, so avoid fingerprint's
     // expensive native-project calculation there. Preview and production stay

apps/mobile/eas.json

@@ -49,6 +49,12 @@
         "image": "macos-tahoe-26.6-xcode-27.1"
       }
     },
+    "testflight": {
+      "extends": "production",
+      "env": {
+        "T3CODE_MOBILE_VERSION": "3.0.0"
+      }
+    },
     "v2-preview": {
       "extends": "production",
       "distribution": "store",
@@ -72,6 +78,9 @@
     }
   },
   "submit": {
+    "testflight": {
+      "extends": "production"
+    },
     "v2-preview": {
       "extends": "production",
       "android": {

apps/mobile/fingerprint.config.js

@@ -8,7 +8,10 @@ const path = require("node:path");
 // version keeps each major's OTAs on its own binaries: a new major reaches
 // users only once its store build is promoted.
 const appConfig = fs.readFileSync(path.join(__dirname, "app.config.ts"), "utf8");
-const majorVersion = appConfig.match(/^ {2}version: "(\d+)\./m)?.[1];
+const version =
+  process.env.T3CODE_MOBILE_VERSION ??
+  appConfig.match(/^ {2}version: repoEnv\.T3CODE_MOBILE_VERSION \?\? "([^"]+)"/m)?.[1];
+const majorVersion = version?.match(/^(\d+)\./)?.[1];
 if (!majorVersion) {
   throw new Error("fingerprint.config.js could not read the app version from app.config.ts");
 }

docs/operations/release.md

@@ -296,6 +296,28 @@ and `VERCEL_ORG_ID` secrets. It also respects the optional `VERCEL_TEAM_SLUG`
 variable. The Vercel project's root directory must be `apps/marketing`.
 Git deployments remain disabled in `apps/marketing/vercel.ts`.
 
+## Mobile TestFlight and store releases
+
+Merges to main publish compatible OTAs and build iOS prereleases with the `testflight`
+profile at version `3.0.0`. Build numbers increment automatically. The committed app
+version remains the App Store release version; Android keeps using that version.
+
+To release iOS, dispatch **Mobile EAS Production** with `mode=build`,
+`profile=production`, `platform=ios`, and the intended version, such as `2.0.1`.
+The workflow commits and pushes the version before building and uploading it.
+Select that build in App Store Connect for App Store review.
+
+To force a TestFlight rebuild, select `profile=testflight`, `platform=ios`, and
+leave the version blank. Submit the first `3.0.0` build for external beta review
+in App Store Connect. Later builds may still require review; uploads alone do
+not guarantee external approval. TestFlight builds expire after 90 days.
+
+Both release and TestFlight binaries receive compatible production-channel OTAs,
+separated by their major-version fingerprints. Manual `mode=update` uses the
+selected profile's version. Before releasing `3.0.0` to the App Store, advance
+`build.testflight.env.T3CODE_MOBILE_VERSION` in `apps/mobile/eas.json` to the next
+unreleased major and get its first beta build approved.
+
 ## Android APK mirror
 
 `.github/workflows/mobile-android-apk.yml` checks Google Play hourly and publishes the newest