iOS TestFlight Upload & Distribution

iOS TestFlight Upload & Distribution

Overview

Fully automated TestFlight deployment:

1. Syncs tunable constants
2. Increments build number
3. Builds and archives the iOS app
4. Exports for App Store
5. Uploads to App Store Connect
6. Waits for Apple processing
7. Adds build to external beta group and submits for Beta App Review
8. Updates server's LATEST_BUILD from Apple's confirmed build number

When to Use

Invoke this skill when the user:

• Asks to "upload to TestFlight"
• Wants to "deploy to TestFlight"
• Says "push a new build" or "send to beta testers"
• Mentions uploading for beta testing

Prerequisites

• Xcode installed with valid signing identity
• App Store Connect Admin API key at ~/​.appstoreconnect/​private_keys/​AuthKey_TF37RTPFSZ.p8
• ExportOptions.plist configured in the iOS project directory
• Python 3 with requests module installed
• SSH access to [email protected] (for server version update)

Quick Method (Recommended)

Run the consolidated Python script:

cd /​Users/​asnaroo/​Desktop/​experiments/​miso/​apps/​firefly/​product/​client/​imp/​ios
python3 testflight-deploy.py

This script performs all 8 steps automatically:

1. sync_tunables() - Syncs live-constants.json to iOS bundle
2. increment_build_number() - Bumps build number via agvtool
3. build_and_archive() - Archives with xcodebuild
4. export_for_app_store() - Exports IPA with ExportOptions.plist
5. upload_to_testflight() - Uploads via altool
6. wait_for_processing() - Polls Apple API until build is VALID
7. distribute_to_testers() - Adds to beta group, submits for review, returns confirmed build number
8. update_server_version() - Updates remote server's LATEST_BUILD via SSH

Key feature: The build number is read back from Apple's API (not assumed from local state), ensuring the server version is always accurate.

Expected Output

============================================================
TestFlight Deployment Pipeline
============================================================
Working directory: /​Users/​asnaroo/​Desktop/​experiments/​miso/​apps/​firefly/​product/​client/​imp/​ios

============================================================
Step 1: Syncing tunables
============================================================
   Synced live-constants.json to iOS bundle

============================================================
Step 2: Incrementing build number
============================================================
   New build number: 18

============================================================
Step 3: Building and archiving
============================================================
   Archive complete

============================================================
Step 4: Exporting for App Store
============================================================
   Export complete

============================================================
Step 5: Uploading to TestFlight
============================================================
   Uploading... (this may take a minute)
   Upload complete

============================================================
Step 6: Waiting for Apple to process build 18
============================================================
   (This typically takes 5-15 minutes)
   Status: PROCESSING (elapsed: 0s)
   Status: PROCESSING (elapsed: 30s)
   Status: VALID (elapsed: 60s)
   Build is ready!

============================================================
Step 7: Distributing to external testers
============================================================
   Getting beta groups...
   Target group: marylebone test group
   Getting latest build from Apple...
   Latest build: 18
   Adding build to marylebone test group...
   Build added to group
   Checking beta review status...
   Submitted! Status: APPROVED
   Distribution complete!

============================================================
Step 8: Updating server version to 18
============================================================
   Restarting server...
   Verifying...
   Server now reports build 18

============================================================
Deployment Complete!
============================================================
Build 18 is now available to external testers.
Server version updated to 18.

How External TestFlight Distribution Works

External testers (unlike internal team members) require builds to go through Beta App Review:

1. Upload - Build appears in App Store Connect with "Processing" status
2. Processing complete - Build state becomes "VALID"
3. Add to group - Build associated with external beta group
4. Submit for review - Creates betaAppReviewSubmission via API
5. Review - Apple reviews (first build: up to 24h, subsequent: usually auto-approved in minutes)
6. Approved - Build appears in TestFlight app on testers' devices

Common Issues

"Missing Compliance" resolved:

• Info.plist includes ITSAppUsesNonExemptEncryption = false
• Compliance popup no longer appears

"Invalid bundle - orientations":

• Add UISupportedInterfaceOrientations to Info.plist with all orientations

Authentication failed (401) for upload:

• Verify Issuer ID is correct: 2e5cbf08-b1a5-4857-b013-30fb6eec002e
• Verify API key file exists at ~/​.appstoreconnect/​private_keys/​AuthKey_TF37RTPFSZ.p8

Build number already exists:

• The script auto-increments, but if needed: agvtool next-version -all

Distribution fails:

• Check build is in VALID state (not still processing)
• Ensure external beta group exists in App Store Connect

Build shows "Ready to Submit" (yellow) instead of "Testing":

• This means Beta App Review submission is missing
• Run the script again - it will submit for review
• First review may take up to 24 hours; subsequent builds are usually auto-approved

Server version update fails:

• Check SSH access: ssh [email protected] "echo ok"
• Manually update: edit ~/​firefly-server/​.env and restart server

Timing

• Sync tunables: ~1 second
• Increment build: ~1 second
• Archive: ~10-15 seconds
• Export: ~5 seconds
• Upload: ~5-30 seconds depending on size
• Local subtotal: ~30 seconds to 1 minute
• Apple processing: ~5-15 minutes
• Distribution + review submission: ~2 seconds
• Server update: ~3 seconds
• Beta App Review: minutes (if previously approved) to 24 hours (first time)

API Credentials

• Admin Key (for REST API): TF37RTPFSZ
• Issuer ID: 2e5cbf08-b1a5-4857-b013-30fb6eec002e
• Key Path: ~/​.appstoreconnect/​private_keys/​AuthKey_TF37RTPFSZ.p8

Important: The REST API requires tokens generated by altool --generate-jwt, not PyJWT. The script handles this automatically.

Scripts Reference

Deprecated scripts (kept for reference):

• testflight-deploy.sh - Old bash script, replaced by Python version
• distribute-testflight.py - Old distribution-only script, now integrated

API Endpoints Used

• GET /​v1/​apps - Find app by bundle ID
• GET /​v1/​apps/​{id}/​betaGroups - List beta groups
• GET /​v1/​builds - Get latest build (used to confirm build number from Apple)
• POST /​v1/​betaGroups/​{id}/​relationships/​builds - Add build to group
• GET /​v1/​builds/​{id}/​betaAppReviewSubmission - Check review status
• POST /​v1/​betaAppReviewSubmissions - Submit for Beta App Review