charlieviettq iOS TestFlight via GitHub Actions
Guide for CI pipelines that build signed iOS apps and upload to TestFlight. Focus on guardrails; user supplies Apple credentials via GitHub Secrets.
When to use
- Automating beta builds on tag or main
- Standardizing Fastlane or xcodebuild upload steps
- Documenting secret requirements for the team
When not to use
- Manual Xcode archive only
- Android Play Console (different pipeline)
- Production App Store release without beta gate
Required secrets (examples)
Store in GitHub Actions secrets — never in repo:
APP_STORE_CONNECT_API_KEYor issuer ID + key ID +.p8contentMATCH_PASSWORD/ certificate repo access if using match- Signing identities via keychain or ephemeral CI keychain
Workflow outline
- Trigger — workflow_dispatch, tag, or branch push (document which)
- Checkout — include submodules if needed
- Ruby/Node setup — if using Fastlane
- Install deps —
bundle install, CocoaPods/SPM resolve - Build — archive release configuration
- Sign — match or manual cert; verify team ID
- Upload —
upload_to_testflightorxcrun altoolsuccessor APIs - Notify — Slack/issue comment on success/failure
Guardrails
- No auto-commit of version bumps unless team explicitly wants it
- No auto-push to main from CI on failure retry loops
- Pin action SHAs or versions; review third-party actions
- Separate workflows for PR (build-only) vs release (upload)
Verification
- Build succeeds on CI before enabling upload
- TestFlight build appears in App Store Connect
- Internal testers can install
Troubleshooting
| Issue | Check |
|---|---|
| Code signing error | Cert expiry, wrong bundle ID, profile mismatch |
| Upload 401 | API key roles, key ID, issuer ID |
| Missing compliance | Export compliance in App Store Connect |