TestFlight release (iOS companion)

Cuts a TestFlight build of TermioMobile by hand. Unlike the Mac app, this is not automated: .github/workflows has no upload step, so nothing happens when a PR merges. Every TestFlight build is a local archive + upload.

Use the asc skill for anything beyond this path (crash triage, App Store submission, metadata). This skill is only the beta-build pipeline, with the repo-specific facts that asc cannot know.

Constants

The build number in the repo is a lie

CURRENT_PROJECT_VERSION in ios/TermioMobile.xcodeproj/project.pbxproj sits at an old value (285 at the time of writing) while App Store Connect is in the 700s. That is deliberate: the bump is applied for the archive and then thrown away.

Never commit the bump. Resolve it against ASC, build, upload, revert:

cd ios
asc xcode version edit --next-build-number --app 6790142237 --platform IOS \
    --project TermioMobile.xcodeproj --output json
# ... archive, export, upload ...
git checkout -- TermioMobile.xcodeproj/project.pbxproj

Uploading a build number at or below the highest one in ASC is rejected, so never guess it from the repo.

Steps

Run from a clean worktree on the commit you want to ship (normally main).

1. Bump — the command above. It reports the number it chose.

2. Archive (Release, signed for distribution):

   cd ios
   asc xcode archive \
     --project TermioMobile.xcodeproj --scheme TermioMobile \
     --configuration Release --clean \
     --archive-path .asc/artifacts/TermioMobile.xcarchive \
     --xcodebuild-flag=-destination --xcodebuild-flag=generic/platform=iOS \
     --xcodebuild-flag=-allowProvisioningUpdates --output json

3. Export. Automatic signing does not work on this Mac — Xcode's stored account token is broken (missing Xcode-Token), so asc xcode export fails with No signing certificate "iOS Distribution" found. Export manually against the profile instead, with ios/.asc/ExportOptions.plist:

   <key>method</key>                <string>app-store-connect</string>
   <key>teamID</key>                <string>5Y27G7B6D8</string>
   <key>signingStyle</key>          <string>manual</string>
   <key>signingCertificate</key>    <string>iPhone Distribution: Jiwei Yuan (5Y27G7B6D8)</string>
   <key>provisioningProfiles</key>  <dict><key>sh.termio.mobile</key><string>Termio iOS App Store</string></dict>

   xcodebuild -exportArchive \
     -archivePath .asc/artifacts/TermioMobile.xcarchive \
     -exportPath .asc/artifacts/export \
     -exportOptionsPlist .asc/ExportOptions.plist

   It still logs the DVTDeveloperAccountManager credential error; with manual signing that is noise, not a failure. Check for ** EXPORT SUCCEEDED **.

4. Upload and wait for processing:

   asc builds upload --app 6790142237 --ipa .asc/artifacts/export/TermioMobile.ipa --wait

5. What to Test — required for external testers, good manners for internal:

   asc builds test-notes create --build-id "BUILD_ID" --locale en-US \
     --whats-new "..."

   Note the subcommand is create; update only edits notes that already exist. One paragraph, concrete, no AI attribution.

6. Distribute.
   • Internal needs no command. Internal groups pick up every processed build automatically — asc builds add-groups on the Internal group fails with "Cannot add internal group to a build." Confirm instead: asc testflight distribution view --build-id "BUILD_ID" → Internal State: IN_BETA_TESTING.

   • Public Beta is external and gated on Beta App Review. Read externalBuildState before doing anything: READY_FOR_BETA_SUBMISSION means it still needs submitting, WAITING_FOR_BETA_REVIEW means it is already in Apple's queue and there is nothing to do but wait, and BETA_TESTING means it is live on the public link. Ask the user before submitting — that ships to real testers.

     It takes two commands, and the first one alone looks like it worked:

     asc builds add-groups --build-id "BUILD_ID" --group fe170244-643a-4c73-9c94-84ab44c254f9
     asc testflight review submit --build-id "BUILD_ID" --confirm

     Adding the group reports success and changes nothing — externalBuildState stays READY_FOR_BETA_SUBMISSION until the build is actually submitted. This holds even for a marketing version that has already cleared review: 1.1 build 951 still had to be submitted on 2026-08-28, having been told here that it would skip the step. What that version buys is the wait, not the submission — the state went WAITING_FOR_REVIEW → IN_BETA_TESTING within a minute rather than hours.

7. Revert the pbxproj bump and delete ios/.asc/ (untracked build artifacts, ~10 MB IPA plus the archive).

Signing assets

The account has one iOS Distribution certificate (M92KPZPT43, expires 2027-08-12) and the Termio iOS App Store profile (R3N9335442). Both were created with the asc CLI, and the identity is installed in the login keychain.

If they are ever missing or expired, recreate them:

mkdir -p ~/Library/Developer/asc-signing/termio && chmod 700 ~/Library/Developer/asc-signing/termio
asc certificates create --certificate-type IOS_DISTRIBUTION --generate-csr \
  --key-out ./dist.key --csr-out ./dist.csr --common-name "Jiwei Yuan"
# save the base64 certificateContent from the response as dist.cer, then:
openssl x509 -inform DER -in dist.cer -out dist.pem
openssl pkcs12 -export -legacy -inkey dist.key -in dist.pem -out dist.p12 \
  -name "iOS Distribution: Jiwei Yuan"
security import dist.p12 -k ~/Library/Keychains/login.keychain-db -T /usr/bin/codesign
asc profiles create --name "Termio iOS App Store" --profile-type IOS_APP_STORE \
  --bundle 97KQ9JGYL8 --certificate "CERT_ID"
asc profiles download --id "PROFILE_ID" --output ./TermioAppStore.mobileprovision
asc profiles local install --path ./TermioAppStore.mobileprovision

-legacy is not optional: OpenSSL 3 defaults to a PKCS#12 MAC that macOS cannot read, and security import fails with "MAC verification failed during PKCS12 import (wrong password?)" — which looks like a password problem and is not one.

Certificates are account-level and limited in number. Creating or revoking one affects every machine that signs this app, so confirm with the user first.

Notes

• ios/dev-run.sh is the device-install loop for development; it has nothing to do with this path and never touches signing for distribution.

Bumping MARKETING_VERSION vs reusing it

Two different numbers move for two different reasons, and only one of them is free:

The rule: reuse the marketing version for iterative betas; bump it only when you are starting a new version train.

Bumping is not free. The first build of a new marketing version has to clear Apple's Beta App Review before any external tester can install it — it sits at externalBuildState: WAITING_FOR_BETA_REVIEW, typically hours. Every later build of that same version still has to be submitted — see step 6, the submission is never automatic — but clears in about a minute instead of hours. Internal testers are never affected either way; they get every processed build immediately (internalBuildState: IN_BETA_TESTING).

So a bump costs one review wait and buys nothing on its own. Bump when the version is about to mean something — an App Store submission, or a batch of work you want to name — and take the review hit once, up front, so the builds that follow it ship instantly.

Consequences worth knowing before you reach for it:

• Pushing another build will not shorten a pending review. A rebuild of the same commit is identical code queued behind the same review. If external access is what you are waiting for, waiting is the action.
• Check state before building anything: asc testflight distribution view --build-id "BUILD_ID". If external already reads WAITING_FOR_BETA_REVIEW, there is nothing useful to upload.
• Review needs the Beta App Review contact, review notes, and What to Test in every locale you ship. Missing any of them turns the wait into a rejection.

Observed 2026-08-13 on 1.1 (build 947): internal IN_BETA_TESTING within minutes, external WAITING_FOR_BETA_REVIEW — the one-time cost of the 1.0 → 1.1 bump, paid so later 1.1 builds go straight out.

An App Store release (as opposed to a beta train) is a separate decision — see docs/RELEASING.md and the asc skill's release-flow reference.