Home / Ops / Deploy and Infrastructure

Affirmology App Store / TestFlight Runbook (both apps)

Updated Jun 27, 2026 · Affirmology_AppStore_TestFlight_Runbook_v1.md

Affirmology App Store / TestFlight Runbook (both apps)

The exact, end to end path to get BOTH iOS apps onto your phone and shareable to testers via TestFlight, then later to the public App Store. No step left to interpretation.

The two apps

Both build the same way. EAS builds in the CLOUD (Expo's servers), so no Xcode build is needed on your Mac. Your local Xcode was only for the Simulator.

Who does what (important)

• YOU = steps only Jeff can do: logging into Expo and Apple, clicking in App Store Connect. These use your credentials and cannot be automated.
• CODE = a command run on the Mac. Claude Code (this session, or any Code session) can run these, or you can paste them into Terminal yourself. They are marked with a code block.
• A plain Cowork web chat CANNOT run the CODE steps (it has no shell on your Mac). If you hand this to Cowork, it can only read you the steps; the commands still have to run on the Mac. The fastest path is to let a Claude Code session on the Mac run the CODE steps while you do the YOU steps.

Phase 0 - One-time setup (YOU, about 15 minutes, do once for both apps)

1. Apple Developer account - already ACTIVE. Nothing to do.

2. Expo account (free): open https://expo.dev and sign up (or sign in if you have one).

3. Install the EAS CLI globally (your npx eas-cli cache is broken, a global install avoids it). In Terminal: npm install -g eas-cli eas login Log in with the Expo account from step 2. Confirm with eas whoami.

4. App Store Connect API key (ONE key, reused for BOTH apps and all future uploads, so EAS can build and upload without you re-logging into Apple each time):

5. Go to https://appstoreconnect.apple.com → Users and Access → Integrations tab → App Store Connect API → press the + to generate a key.
6. Name it Affirmology EAS, role App Manager, Generate.
7. Download the .p8 file (you can only download it once) and note the Key ID and the Issuer ID (shown on that page).
8. Save the .p8 into both app folders as asc-api-key.p8: affirmology-atlas/asc-api-key.p8 and affirmology-app/asc-api-key.p8 (it is gitignored as a secret). Give Claude Code the Key ID + Issuer ID, or fill them into each app's eas.json under submit.production.ios (ascApiKeyId, ascApiKeyIssuerId).

After Phase 0 you never repeat it. Phases 1 and 2 are the same recipe per app.

Phase 1 - Atlas to TestFlight

Run all CODE steps from /Users/jeffreyparker/CLAUDE/AFFIRMOLOGY/affirmology-atlas.

1. Link the project to EAS. CODE: eas init Pick your account, accept the suggested name (affirmology-atlas). This writes an EAS projectId into app.json.

2. Build in the cloud. CODE: eas build --platform ios --profile production - The FIRST time, EAS asks YOU to authenticate with Apple (a login link in the terminal). Approve it. EAS then auto-creates the iOS signing (distribution certificate + provisioning profile) AND creates the App Store Connect app record for ai.affirmology.atlas. - The build runs on Expo's servers, about 15 to 25 minutes. You can close the terminal; it keeps building. eas build:list shows status.

3. Upload to TestFlight. CODE (uses the ASC API key, no Apple login needed): eas submit --platform ios --profile production --latest

4. Apple processes the build (about 10 to 30 minutes). It then shows up in App Store Connect → your app → TestFlight.

5. Turn on external testing + the public link. YOU, in App Store Connect → Atlas → TestFlight:

6. Left side, under External Testing, press + to create a group: name it Atlas Creators.
7. Open the group → Builds tab → + → add the processed build.
8. Fill Test Information: "What to Test" (one line, e.g. "Create audios with Hermes, play and review in the Listening Room") and your contact email, then Submit for Review (Apple's Beta App Review, usually under a day, often a few hours).

9. Once approved, in the group turn ON Public Link and copy it.

10. Install on your phone + share. YOU:

11. On your iPhone, install TestFlight from the App Store (one time).
12. Open the public link from step 5.4 → Install → Atlas is on your phone.
13. Send the same link to Sol and Colin. They install TestFlight + tap the link. Done.

Phase 2 - Affirmology (consumer app) to TestFlight

Identical recipe, run from /Users/jeffreyparker/CLAUDE/AFFIRMOLOGY/affirmology-app. The Expo login and the ASC API key are already done (Phase 0); only the per-app build + ASC group are new.

1. CODE: eas init
2. CODE: eas build --platform ios --profile production (Apple creds reuse what Atlas set up; creates the ai.affirmology.app app record)
3. CODE: eas submit --platform ios --profile production --latest
4. Apple processing (10 to 30 min).
5. YOU, App Store Connect → Affirmology → TestFlight: create an External group Affirmology Beta, add the build, fill Test Information, Submit for Beta Review, turn on the Public Link.
6. YOU: install via the link, share it with beta testers.

This is the link you give to the wider July beta: anyone with it installs (up to 10,000 testers), no account management.

Phase 3 - Public App Store release (later, after beta)

Per app, when the beta is solid. This needs marketing assets, so it is its own prep task.

1. YOU, App Store Connect → app → create the App Store version (App Store tab): - Description, keywords, support URL, privacy policy URL (required), age rating, category, pricing. - Screenshots (6.7" + 6.5" iPhone sizes, required).
2. Attach a build (a TestFlight build can be promoted to the App Store version).
3. YOU: Submit for Review (App Store Review, about 1 to 3 days). On approval, release (manual or auto).

Flag: do not start Phase 3 until the screenshots + description + privacy policy are written (a separate deliverable). TestFlight (Phases 1 and 2) needs none of that.

Notes and gotchas

• Both apps use react-native-track-player (native), so they cannot run in Expo Go and must be built by EAS. That is exactly what this runbook does.
• Atlas also added expo-speech-recognition (the voice mic). Already prebuilt + compile-verified, so the EAS build includes it.
• The ASC API key (Phase 0.4) is reused for both apps and every future upload. Generate once.
• Push notifications: both apps include expo-notifications. Real push needs an APNs key added in App Store Connect later; it is NOT needed to install or test via TestFlight.
• Version bumps: eas.json production has autoIncrement, so the iOS build number bumps automatically on each build. The marketing version is 1.0.0 in each app.json; bump that for a public release.
• If eas build ever asks about the bundle identifier, accept the one already in app.json (ai.affirmology.atlas / ai.affirmology.app); they are approved.

The single first action (unblocks everything)

In Terminal:

npm install -g eas-cli
eas login

Then generate the ASC API key (Phase 0.4). Once those exist, a Claude Code session on the Mac can run every CODE step in Phases 1 and 2 back to back, pausing only when Apple needs your approval.