co-labs-co Skill: iOS CI/CD with TestFlight
Automate iOS app builds, versioning, and TestFlight deployment using GitHub Actions with semantic-release for conventional commits-based version management.
When to Use
- Setting up automated TestFlight deployments for iOS apps
- Implementing semantic versioning with conventional commits
- Configuring Apple code signing in CI/CD pipelines
- Automating version bumps and changelog generation
- Building release pipelines that trigger on Git tags
Key Concepts
Version Management for iOS
- CFBundleShortVersionString (Marketing version): User-visible version (1.2.3)
- CFBundleVersion (Build number): Must increment with each App Store Connect submission
Apple Code Signing Components
- Distribution Certificate (.p12): Proves your identity to Apple
- Provisioning Profile (.mobileprovision): Links app, certificate, and distribution method
- App Store Connect API Key (.p8): Authenticates CLI uploads
GitHub Actions Secrets Required
APPLE_TEAM_ID
DISTRIBUTION_CERTIFICATE_BASE64
DISTRIBUTION_CERTIFICATE_PASSWORD
PROVISIONING_PROFILE_BASE64
APP_STORE_CONNECT_API_KEY_ID
APP_STORE_CONNECT_API_ISSUER_ID
APP_STORE_CONNECT_API_KEY_BASE64
Implementation Guide
Step 1: Configure semantic-release
package.json:
{
"devDependencies": {
"@semantic-release/changelog": "^6.0.3",
"@semantic-release/commit-analyzer": "^13.0.0",
"@semantic-release/exec": "^7.1.0",
"@semantic-release/git": "^10.0.1",
"@semantic-release/github": "^12.0.2",
"@semantic-release/release-notes-generator": "^14.0.0",
"semantic-release": "^25.0.2"
}
}
.releaserc.json:
{
"branches": ["main"],
"tagFormat": "v${version}",
"plugins": [
["@semantic-release/commit-analyzer", {
"preset": "conventionalcommits",
"releaseRules": [
{ "type": "feat", "release": "minor" },
{ "type": "fix", "release": "patch" },
{ "type": "perf", "release": "patch" }
]
}],
["@semantic-release/release-notes-generator", {
"preset": "conventionalcommits"
}],
["@semantic-release/changelog", {
"changelogFile": "CHANGELOG.md"
}],
["@semantic-release/exec", {
"prepareCmd": "scripts/update-ios-version.sh ${nextRelease.version}"
}],
["@semantic-release/git", {
"assets": ["CHANGELOG.md", "YourApp/Info.plist"],
"message": "chore(release): ${nextRelease.version} [skip ci]"
}],
["@semantic-release/github"]
]
}
scripts/update-ios-version.sh:
#!/bin/bash
VERSION=$1
BUILD_NUMBER=$(date +%Y%m%d%H%M)
/usr/libexec/PlistBuddy -c "Set :CFBundleShortVersionString $VERSION" "YourApp/Info.plist"
/usr/libexec/PlistBuddy -c "Set :CFBundleVersion $BUILD_NUMBER" "YourApp/Info.plist"
Step 2: TestFlight Workflow
.github/workflows/testflight.yml:
name: TestFlight
version: 0.1.0
author: cmtzco
on:
push:
tags: ['v*.*.*']
workflow_dispatch:
jobs:
build-and-upload:
runs-on: macos-15
steps:
- uses: actions/checkout@v4
- name: Set version
id: version
run: |
if [[ "${{ github.ref }}" == refs/tags/v* ]]; then
VERSION="${GITHUB_REF#refs/tags/v}"
else
VERSION=$(/usr/libexec/PlistBuddy -c "Print :CFBundleShortVersionString" "YourApp/Info.plist")
fi
BUILD_NUMBER=$(date +%Y%m%d%H%M)
echo "version=$VERSION" >> $GITHUB_OUTPUT
echo "build_number=$BUILD_NUMBER" >> $GITHUB_OUTPUT
- name: Install certificate and profile
env:
DISTRIBUTION_CERTIFICATE_BASE64: ${{ secrets.DISTRIBUTION_CERTIFICATE_BASE64 }}
DISTRIBUTION_CERTIFICATE_PASSWORD: ${{ secrets.DISTRIBUTION_CERTIFICATE_PASSWORD }}
PROVISIONING_PROFILE_BASE64: ${{ secrets.PROVISIONING_PROFILE_BASE64 }}
KEYCHAIN_PASSWORD: ${{ github.run_id }}
run: |
CERTIFICATE_PATH=$RUNNER_TEMP/cert.p12
PROFILE_PATH=$RUNNER_TEMP/profile.mobileprovision
KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db
echo -n "$DISTRIBUTION_CERTIFICATE_BASE64" | base64 --decode -o "$CERTIFICATE_PATH"
echo -n "$PROVISIONING_PROFILE_BASE64" | base64 --decode -o "$PROFILE_PATH"
security create-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
security set-keychain-settings -lut 21600 "$KEYCHAIN_PATH"
security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
security import "$CERTIFICATE_PATH" -P "$DISTRIBUTION_CERTIFICATE_PASSWORD" -A -t cert -f pkcs12 -k "$KEYCHAIN_PATH"
security set-key-partition-list -S apple-tool:,apple: -k "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
security list-keychain -d user -s "$KEYCHAIN_PATH"
mkdir -p ~/Library/MobileDevice/Provisioning\ Profiles
cp "$PROFILE_PATH" ~/Library/MobileDevice/Provisioning\ Profiles/
- name: Build archive
run: |
xcodebuild archive \
-project "YourApp.xcodeproj" \
-scheme "YourApp" \
-destination "generic/platform=iOS" \
-archivePath "$RUNNER_TEMP/App.xcarchive" \
CODE_SIGN_STYLE=Manual \
DEVELOPMENT_TEAM="${{ secrets.APPLE_TEAM_ID }}"
- name: Export IPA
run: |
cat > "$RUNNER_TEMP/ExportOptions.plist" << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>method</key>
<string>app-store-connect</string>
<key>teamID</key>
<string>${{ secrets.APPLE_TEAM_ID }}</string>
</dict>
</plist>
EOF
xcodebuild -exportArchive \
-archivePath "$RUNNER_TEMP/App.xcarchive" \
-exportPath "$RUNNER_TEMP/export" \
-exportOptionsPlist "$RUNNER_TEMP/ExportOptions.plist"
- name: Upload to TestFlight
env:
APP_STORE_CONNECT_API_KEY_ID: ${{ secrets.APP_STORE_CONNECT_API_KEY_ID }}
APP_STORE_CONNECT_API_ISSUER_ID: ${{ secrets.APP_STORE_CONNECT_API_ISSUER_ID }}
APP_STORE_CONNECT_API_KEY_BASE64: ${{ secrets.APP_STORE_CONNECT_API_KEY_BASE64 }}
run: |
API_KEY_PATH=$RUNNER_TEMP/AuthKey.p8
echo -n "$APP_STORE_CONNECT_API_KEY_BASE64" | base64 --decode -o "$API_KEY_PATH"
mkdir -p ~/.private_keys
cp "$API_KEY_PATH" ~/.private_keys/AuthKey_${APP_STORE_CONNECT_API_KEY_ID}.p8
IPA_PATH=$(find "$RUNNER_TEMP/export" -name "*.ipa" | head -1)
xcrun altool --upload-app \
--type ios \
--file "$IPA_PATH" \
--apiKey "$APP_STORE_CONNECT_API_KEY_ID" \
--apiIssuer "$APP_STORE_CONNECT_API_ISSUER_ID"
- name: Clean up keychain
if: always()
run: security delete-keychain $RUNNER_TEMP/app-signing.keychain-db 2>/dev/null || true
Common Pitfalls
Code Signing Errors
- "No signing certificate": Ensure certificate exported with private key as .p12
- "Provisioning profile doesn't match": Bundle ID must match exactly
- "Team ID mismatch": Use 10-character Team ID, not team name
Build Number Conflicts
- "Build already processed": Build numbers must strictly increase
- Fix: Timestamp format (YYYYMMDDHHMM) prevents duplicates
Secrets Encoding
# Correct encoding on macOS
base64 -i certificate.p12 -o cert.base64
# Use echo -n when decoding to avoid trailing newlines
echo -n "$SECRET" | base64 --decode -o file
semantic-release Issues
- "ENOGHTOKEN": Ensure GITHUB_TOKEN has write permissions
- "No release": Commits must follow conventional format (
feat:,fix:) - "PlistBuddy not found": Must run on macOS runner
Runner Selection
- macos-15: Recommended (latest Xcode, Apple Silicon)
- macos-latest: Will migrate to macos-15 in August 2025
References
- GitHub: Installing Apple Certificate on macOS Runners
- GitHub Actions macOS Runners
- semantic-release Documentation
- Apple: Creating API Keys
Derived from CarSeet project - .github/workflows/testflight.yml, .releaserc.json