TestFlight

// Distribute iOS and macOS beta builds with TestFlight, tester management, and CI/CD automation.

$ git log --oneline --stat

stars:1,933

forks:367

updated:March 4, 2026

SKILL.mdreadonly

SKILL.md Frontmatter

nameTestFlight

slugtestflight

version1.0.0

homepagehttps://clawic.com/skills/testflight

descriptionDistribute iOS and macOS beta builds with TestFlight, tester management, and CI/CD automation.

metadata[object Object]

When to Use

User needs to distribute beta builds via TestFlight. Agent handles App Store Connect setup, tester groups, build uploads, and CI/CD integration.

Quick Reference

Topic	File
CI/CD automation	`ci-cd.md`

Core Rules

1. App Store Connect Setup First

Before uploading:

Bundle ID registered in Developer Portal
App created in App Store Connect
App-specific password or API key configured

2. Build Requirements

Every TestFlight build needs:

Unique build number (CFBundleVersion) - increment ALWAYS
Valid provisioning profile (App Store distribution)
No missing compliance declarations

3. Tester Group Strategy

Group	Purpose	Limit
Internal	Team members with App Store Connect access	100
External	Beta testers, requires review	10,000

Internal builds available immediately. External requires Apple review (24-48h first time).

4. Upload Methods

Method	Best For
Xcode	Manual, one-off uploads
`xcrun altool`	Scripts, CI without fastlane
Fastlane	Full automation, multiple apps
Xcode Cloud	Apple-native CI/CD
Transporter	GUI for non-developers

5. Build Expiration

TestFlight builds expire after 90 days. Plan releases accordingly.

TestFlight Traps

Build number not incremented - rejected immediately, must bump and rebuild
Missing export compliance - stuck in "Processing" until answered in App Store Connect
External testers on first build - requires full beta review, use internal first
Expired provisioning profile - upload fails silently, check before archiving
App-specific password in CI - use App Store Connect API key instead (more secure, no 2FA issues)

CI/CD Quick Setup

App Store Connect API Key (Recommended)

App Store Connect > Users > Keys > App Store Connect API
Generate key with "App Manager" role
Download .p8 file (only shown ONCE)
Note: Issuer ID, Key ID

Fastlane Upload

# In Fastfile
lane :beta do
  build_app(scheme: "MyApp")
  upload_to_testflight(
    api_key_path: "fastlane/api_key.json",
    skip_waiting_for_build_processing: true
  )
end

xcrun altool (No Fastlane)

xcrun altool --upload-app \
  --type ios \
  --file "MyApp.ipa" \
  --apiKey "KEY_ID" \
  --apiIssuer "ISSUER_ID"

Security & Privacy

Data that leaves your machine:

IPA/app binary uploaded to Apple servers
Build metadata (version, bundle ID, team)

Data that stays local:

API keys and certificates (keep in Keychain)
Source code (not uploaded)

This skill does NOT:

Store Apple credentials in plain text
Share builds outside Apple's infrastructure

Related Skills

Install with clawhub install <slug> if user confirms:

ios — iOS development patterns
xcode — Xcode workflows
flutter — cross-platform builds

Feedback

If useful: clawhub star testflight
Stay updated: clawhub sync