Testflight

TestFlight Deploy Skill

Deploy an iOS app to TestFlight in one command. Works locally on a Mac or remotely via SSH to a Mac build host.

Usage

/testflight — bump build, archive, export, upload. Auto-increments build number. /testflight — deploy with a specific build number. /testflight sync — sync web assets from the dev machine first, then deploy.

Modes

• Local (running Claude Code on a Mac): Set TF_MAC_HOST to local or leave it unset. The deploy script runs directly on this machine.
• Remote (running Claude Code on Windows/Linux, building on a Mac): Set TF_MAC_HOST to user@host. The skill SSHs to the Mac to run the deploy script.

Configuration

All values come from environment variables or a .testflight.env file in your project root. Copy examples/.testflight.env.example and fill in your values.

| Variable | Description | Example | |---|---|---| | TF_MAC_HOST | local or SSH user@host. If unset, defaults to local | user@192.168.1.68 | | TF_PROJECT_DIR | Project directory (local path or path on the Mac) | ~/my-app | | TF_DEPLOY_SCRIPT | Deploy script filename (relative to project) | deploy-testflight.sh | | TF_SYNC_SOURCE | Local directory to sync (for sync mode, remote only) | /path/to/public/ | | TF_SYNC_DEST | Remote directory to sync to (remote only) | ~/my-app/public/ | | TF_SYNC_FILES | Space-separated list of files to sync (optional, syncs all if omitted) | app.js style.css index.html |

What it does

Local mode (TF_MAC_HOST unset or local)

1. (If sync) Copy files from TF_SYNC_SOURCE to TF_SYNC_DEST locally
2. Run TF_PROJECT_DIR/TF_DEPLOY_SCRIPT [build_number] directly
3. Report the result (delivery UUID, build number)

Remote mode (TF_MAC_HOST set to user@host)

1. (If sync) SCP files from TF_SYNC_SOURCE to TF_SYNC_DEST on the Mac
2. SSH to TF_MAC_HOST
3. Run TF_PROJECT_DIR/TF_DEPLOY_SCRIPT [build_number]
4. Report the result (delivery UUID, build number)

Steps to run

# Load config
source /path/to/project/.testflight.env

# Determine mode
if [ -z "$TF_MAC_HOST" ] || [ "$TF_MAC_HOST" = "local" ]; then
    # Local: run directly
    cd ${TF_PROJECT_DIR} && ./${TF_DEPLOY_SCRIPT} [build_number]
else
    # Remote: SSH
    ssh ${TF_MAC_HOST} "cd ${TF_PROJECT_DIR} && ./${TF_DEPLOY_SCRIPT} [build_number]"
fi

The deploy script

The skill expects a deploy-testflight.sh in your project that handles:

1. Build number bump — auto-increment or accept as argument
2. Keychain unlock — so codesigning works (required over SSH, optional locally)
3. Archive — xcodebuild archive
4. Export IPA — xcodebuild -exportArchive with App Store Connect method
5. Upload — xcrun altool --upload-app or xcrun notarytool

See scripts/deploy-testflight.sh for a complete, configurable template.

Troubleshooting

• errSecInternalComponent: Keychain not unlocked. Ensure the deploy script runs security unlock-keychain.
• CURRENT_PROJECT_VERSION duplicate: Build number already uploaded. Bump manually or let auto-increment handle it.
• Missing code-signing certificate: Export step failed. Ensure security default-keychain -s ran before export.
• SSH hangs: Use LAN IP, not Tailscale/VPN, for build machines on the same network.
• Local mode, keychain prompt: If running locally and the GUI keychain dialog appears, either enter your password or set TF_KEYCHAIN_PASS to unlock programmatically.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: KewkLW
• Source: KewkLW/claude-testflight-skill
• License: MIT

Install and usage instructions live in the source repository linked above.