release-testflight-ios

name	release-testflight-ios
description	Archive, export, upload, and distribute an iOS app to TestFlight via App Store Connect using asc.
user-invocable	true
disable-model-invocation	true
argument-hint	[version]

Run the full iOS TestFlight release pipeline for the current project. This skill handles archive, IPA export, upload to App Store Connect, and optional TestFlight group distribution — all via asc.

Prerequisites

The project must have:

• An Xcode project (.xcodeproj) or xcodegen project spec (project.yml)
• An export options plist for App Store / TestFlight signing (e.g. Configs/TestFlightExportOptions.plist or config/exportOptions.plist)
• asc CLI installed and configured (API key auth or --profile)
• xcbeautify installed
• ASC_APP_ID set in .env or shell environment

Environment Variables

All can be set in a .env file at the project root or exported in the shell.

Variable	Required	Default	Description
ASC_APP_ID	Yes	—	App Store Connect app ID
TESTFLIGHT_GROUP	No	—	TestFlight group name for auto-distribution
TESTFLIGHT_SCHEME	No	App name	Xcode scheme to archive
TESTFLIGHT_CONFIGURATION	No	Release	Xcode build configuration
TESTFLIGHT_DESTINATION	No	generic/platform=iOS	Xcode destination
TESTFLIGHT_VERSION	No	—	Override MARKETING_VERSION
TESTFLIGHT_BUILD_NUMBER	No	—	Override CURRENT_PROJECT_VERSION
TESTFLIGHT_NOTES	No	—	What to Test notes
TESTFLIGHT_LOCALE	No	en-US	Locale for test notes
TESTFLIGHT_NOTIFY	No	false	Notify testers on distribution
TESTFLIGHT_WAIT	No	true	Wait for build processing to complete
TESTFLIGHT_TIMEOUT	No	30m	Max wait time for processing
TESTFLIGHT_DRY_RUN	No	false	Validate without uploading
TESTFLIGHT_ALLOW_PROVISIONING_UPDATES	No	true	Pass -allowProvisioningUpdates
APP_STORE_CONNECT_KEY_ID	No	—	API key ID for xcodebuild auth
APP_STORE_CONNECT_ISSUER_ID	No	—	Issuer ID for xcodebuild auth
APP_STORE_CONNECT_KEY_PATH	No	—	Path to .p8 private key
ASC_PROFILE	No	—	Named asc auth profile

Steps

1. Detect project settings — find the .xcodeproj, scheme, export options plist, and app name from the working directory. Check the justfile, project.yml, or xcodeproj. If xcodegen is available and a project.yml exists, run xcodegen generate first.

2. Load environment — source .env if present. Normalize auth env vars (ASC_KEY_ID, ASC_ISSUER_ID, ASC_PRIVATE_KEY_PATH from their APP_STORE_CONNECT_* counterparts).

3. Validate access — confirm asc can reach the app:

asc apps get --id "$ASC_APP_ID" --output json

4. Archive the app:

xcodebuild \
  -project $PROJECT \
  -scheme $SCHEME \
  -configuration Release \
  -destination "generic/platform=iOS" \
  -archivePath build/testflight/$APP_NAME.xcarchive \
  -allowProvisioningUpdates \
  archive 2>&1 | xcbeautify

5. Export the IPA:

xcodebuild -exportArchive \
  -archivePath build/testflight/$APP_NAME.xcarchive \
  -exportPath build/testflight/export \
  -exportOptionsPlist $EXPORT_OPTIONS_PLIST \
  -allowProvisioningUpdates 2>&1 | xcbeautify

6. Read archive metadata — extract version and build number from the archive's Info.plist:

VERSION=$(plutil -extract 'ApplicationProperties.CFBundleShortVersionString' raw -o - build/testflight/$APP_NAME.xcarchive/Info.plist)
BUILD=$(plutil -extract 'ApplicationProperties.CFBundleVersion' raw -o - build/testflight/$APP_NAME.xcarchive/Info.plist)

7. Upload and distribute — if TESTFLIGHT_GROUP is set, use asc publish testflight for a single upload+distribute step:

asc publish testflight \
  --app "$ASC_APP_ID" \
  --ipa build/testflight/export/*.ipa \
  --group "$TESTFLIGHT_GROUP" \
  --platform IOS \
  --wait

Otherwise, upload the build and wait for processing:

asc builds upload \
  --app "$ASC_APP_ID" \
  --ipa build/testflight/export/*.ipa \
  --version "$VERSION" \
  --build-number "$BUILD"

Then poll for processing completion:

asc builds find --app "$ASC_APP_ID" --build-number "$BUILD" --output json

Check processingState — VALID means ready, FAILED/INVALID means stop.

Important

• Always confirm with the user before starting (this uploads to App Store Connect)
• Run each step sequentially — each depends on the previous
• If archive or export fails, do NOT proceed to upload
• Show the user the version, build number, and processing status when done
• For dry-run mode, pass --dry-run to asc builds upload to validate without uploading