fastlane

Fastlane

Automate iOS and macOS builds, code signing, TestFlight distribution, and App Store submissions — all from one-off CLI commands. No Fastfile required.

---

Verify Installation

fastlane --version

If not installed:

brew install fastlane

Or via RubyGems:

sudo gem install fastlane -NV

After install, add to your shell profile:

export PATH="$HOME/.fastlane/bin:$PATH"

---

Authentication

App Store Connect API Key (Preferred)

API keys avoid 2FA prompts and are the recommended approach for automation and CI.

1. Generate a key at App Store Connect → Users and Access → Keys.
2. Download the .p8 file.
3. Set environment variables:

export APP_STORE_CONNECT_API_KEY_KEY_ID="XXXXXXXXXX"
export APP_STORE_CONNECT_API_KEY_ISSUER_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export APP_STORE_CONNECT_API_KEY_KEY_FILEPATH="/path/to/AuthKey_XXXXXXXXXX.p8"

Or pass the key inline as JSON:

export APP_STORE_CONNECT_API_KEY_KEY='{"key_id":"XXXXXXXXXX","issuer_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","key_filepath":"/path/to/AuthKey.p8"}'

Agent guidance: Always prefer API key authentication. Only fall back to Apple ID when the user explicitly does not have API key access.

Apple ID Fallback

export FASTLANE_USER="user@example.com"
export FASTLANE_PASSWORD="app-specific-password"

Generate an app-specific password at appleid.apple.com. If 2FA is enabled, you may also need:

export FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"
export SPACESHIP_2FA_SMS_DEFAULT_PHONE_NUMBER="+1 (xxx) xxx-xxxx"

Environment Variables — Authentication Reference

---

One-Off Action Execution

Fastlane actions can be run directly from the CLI without a Fastfile:

fastlane run <action_name> key:value key2:value2

Discover available actions:

fastlane actions                    # List all actions
fastlane action <action_name>      # Show details for one action
fastlane search_actions <query>    # Search by keyword

Agent guidance: Use fastlane run <action> for one-off tasks. This is the core pattern — every section below shows both the shorthand tool command and the fastlane run equivalent.

---

pilot (TestFlight)

Upload a Build to TestFlight

fastlane pilot upload --ipa "/path/to/App.ipa"

Equivalent:

fastlane run upload_to_testflight ipa:"/path/to/App.ipa"

With API key:

fastlane pilot upload \
  --ipa "/path/to/App.ipa" \
  --api_key_path "/path/to/api_key.json"

List Builds

fastlane pilot builds

Manage Testers

# Add a tester
fastlane pilot add email:"tester@example.com" group_name:"Beta Testers"

# Remove a tester
fastlane pilot remove email:"tester@example.com"

# List testers
fastlane pilot list

Distribute to External Testers

fastlane pilot distribute \
  --build_number "42" \
  --groups "External Beta" \
  --changelog "Bug fixes and performance improvements"

Common pilot Flags

---

deliver (App Store)

Submit to App Store

fastlane deliver --ipa "/path/to/App.ipa" --submit_for_review

Equivalent:

fastlane run upload_to_app_store ipa:"/path/to/App.ipa" submit_for_review:true

Upload Metadata Only

fastlane deliver --skip_binary_upload --skip_screenshots

Upload Screenshots Only

fastlane deliver --skip_binary_upload --skip_metadata

Download Existing Metadata

fastlane deliver download_metadata --app_identifier "com.example.app"

Download Existing Screenshots

fastlane deliver download_screenshots --app_identifier "com.example.app"

Common deliver Flags

---

gym / build_app (Build)

Build an IPA

fastlane gym \
  --workspace "App.xcworkspace" \
  --scheme "App" \
  --export_method "app-store" \
  --output_directory "./build"

Equivalent:

fastlane run build_app \
  workspace:"App.xcworkspace" \
  scheme:"App" \
  export_method:"app-store" \
  output_directory:"./build"

Build with Xcode Project (no workspace)

fastlane gym \
  --project "App.xcodeproj" \
  --scheme "App" \
  --export_method "app-store"

Export Methods

Common gym Flags

Agent guidance: If the project has a .xcworkspace (e.g., uses CocoaPods or SPM), always use --workspace. Only use --project when there is no workspace.

---

match (Code Signing)

Sync certificates and provisioning profiles from a shared Git repo or cloud storage.

Sync for App Store

fastlane match appstore --app_identifier "com.example.app"

Equivalent:

fastlane run sync_code_signing type:"appstore" app_identifier:"com.example.app"

Sync for Development

fastlane match development --app_identifier "com.example.app"

Sync for Ad Hoc

fastlane match adhoc --app_identifier "com.example.app"

Read-Only Mode (CI)

fastlane match appstore --readonly --app_identifier "com.example.app"

Agent guidance: Always use --readonly on CI servers. This prevents accidentally creating new certificates and disrupting the team.

Nuke (Reset All Certificates)

# Remove all certificates and profiles for a type
fastlane match nuke appstore
fastlane match nuke development

Warning: Nuke is destructive and irreversible. Always confirm with the user before running nuke commands.

Common match Flags

Agent guidance: Prefer match over cert + sigh for teams. It centralizes signing and avoids the "works on my machine" problem.

---

scan / run_tests (Testing)

Run Tests

fastlane scan \
  --workspace "App.xcworkspace" \
  --scheme "AppTests" \
  --device "iPhone 16 Pro"

Equivalent:

fastlane run run_tests \
  workspace:"App.xcworkspace" \
  scheme:"AppTests" \
  device:"iPhone 16 Pro"

Run on Multiple Devices

fastlane scan \
  --workspace "App.xcworkspace" \
  --scheme "AppTests" \
  --devices "iPhone 16 Pro,iPad Pro (13-inch) (M4)"

Output Formats

fastlane scan \
  --scheme "AppTests" \
  --output_types "html,junit" \
  --output_directory "./test_results"

Common scan Flags

---

snapshot (Screenshots)

Capture App Store screenshots across devices and languages automatically.

Capture Screenshots

fastlane snapshot \
  --workspace "App.xcworkspace" \
  --scheme "AppUITests" \
  --devices "iPhone 16 Pro Max,iPhone SE (3rd generation),iPad Pro (13-inch) (M4)" \
  --languages "en-US,es-ES,fr-FR" \
  --output_directory "./screenshots"

Equivalent:

fastlane run capture_screenshots \
  workspace:"App.xcworkspace" \
  scheme:"AppUITests" \
  devices:"iPhone 16 Pro Max,iPhone SE (3rd generation),iPad Pro (13-inch) (M4)" \
  languages:"en-US,es-ES,fr-FR" \
  output_directory:"./screenshots"

Common snapshot Flags

---

cert + sigh (Certificates & Profiles)

Standalone certificate and provisioning profile management.

Create/Fetch a Certificate

fastlane cert --development
fastlane cert  # Distribution certificate by default

Equivalent:

fastlane run get_certificates development:true

Create/Fetch a Provisioning Profile

# App Store profile
fastlane sigh --app_identifier "com.example.app"

# Development profile
fastlane sigh --development --app_identifier "com.example.app"

# Ad hoc profile
fastlane sigh --adhoc --app_identifier "com.example.app"

Equivalent:

fastlane run get_provisioning_profile app_identifier:"com.example.app"

Repair Profiles

fastlane sigh repair

Common Flags

Agent guidance: For individual developers, cert + sigh works fine. For teams, recommend match instead — it prevents certificate conflicts.

---

precheck (Validation)

Validate app metadata before submitting to avoid App Store Review rejections.

fastlane precheck --app_identifier "com.example.app"

Equivalent:

fastlane run check_app_store_metadata app_identifier:"com.example.app"

What precheck Validates

• Unreachable URLs in metadata
• Mentions of other platforms (Android, etc.)
• Profanity or inappropriate content
• Placeholder text
• Copyright date accuracy

---

pem (Push Notification Certificates)

Generate push notification certificates for APNs.

fastlane pem --app_identifier "com.example.app" --output_path "./certs"

Equivalent:

fastlane run get_push_certificate app_identifier:"com.example.app" output_path:"./certs"

Common pem Flags

Agent guidance: For modern projects using token-based APNs (.p8 key), push certs are unnecessary. Only use pem if the project specifically uses certificate-based APNs.

---

frameit (Screenshot Frames)

Add device bezels and titles to screenshots for App Store presentation.

fastlane frameit --path "./screenshots"

With titles:

fastlane frameit silver --path "./screenshots"

Equivalent:

fastlane run frame_screenshots path:"./screenshots"

A Framefile.json in the screenshots directory controls titles, fonts, and colors.

---

Common Workflows

Build + Upload to TestFlight

fastlane gym \
  --workspace "App.xcworkspace" \
  --scheme "App" \
  --export_method "app-store" \
  --output_directory "./build" && \
fastlane pilot upload \
  --ipa "./build/App.ipa" \
  --changelog "Latest build from CI"

Build + Submit to App Store

fastlane gym \
  --workspace "App.xcworkspace" \
  --scheme "App" \
  --export_method "app-store" \
  --output_directory "./build" && \
fastlane deliver \
  --ipa "./build/App.ipa" \
  --submit_for_review \
  --automatic_release \
  --force

Sync Signing + Build + Upload

fastlane match appstore \
  --app_identifier "com.example.app" \
  --readonly && \
fastlane gym \
  --workspace "App.xcworkspace" \
  --scheme "App" \
  --export_method "app-store" \
  --output_directory "./build" && \
fastlane pilot upload \
  --ipa "./build/App.ipa"

Test + Build + Upload

fastlane scan \
  --workspace "App.xcworkspace" \
  --scheme "AppTests" && \
fastlane gym \
  --workspace "App.xcworkspace" \
  --scheme "App" \
  --export_method "app-store" \
  --output_directory "./build" && \
fastlane pilot upload \
  --ipa "./build/App.ipa"

Screenshots + Frames + Upload

fastlane snapshot \
  --workspace "App.xcworkspace" \
  --scheme "AppUITests" \
  --output_directory "./screenshots" && \
fastlane frameit silver --path "./screenshots" && \
fastlane deliver --skip_binary_upload --skip_metadata

---

Environment Variables

General

CI-Specific

Xcode

---

Notes

CLI Syntax Rules

• All fastlane run parameters use key:value syntax (no dashes, no equals signs).
• Tool shorthand commands (fastlane gym, fastlane pilot) use --key value or --key "value" syntax.
• Boolean parameters: true/false for fastlane run, --flag/no flag for shorthand.
• Array parameters: comma-separated strings (e.g., devices:"iPhone 16,iPad Pro").
• Paths with spaces must be quoted.

Error Handling

• Session expired: Re-authenticate with fastlane spaceauth -u user@example.com or refresh API key.
• Code signing errors: Run fastlane match to sync, or security find-identity -v -p codesigning to verify local certs.
• "Could not find App": Verify app_identifier matches the bundle ID registered in App Store Connect.
• Timeout on upload: Set FASTLANE_XCODEBUILD_SETTINGS_TIMEOUT=120 and retry.
• Profile mismatch: Run fastlane sigh repair or fastlane match with --force.

Agent Tips

When a user asks to "deploy" or "release" an iOS app, the typical flow is: match (sign) → gym (build) → pilot (TestFlight) or deliver (App Store).

If the user has a Fastfile, respect it. But for one-off commands, always use the CLI syntax shown in this skill.

Always check for an existing .xcworkspace before defaulting to .xcodeproj. Run ls *.xcworkspace to verify.

For CI environments, always use --readonly with match and set the CI=true environment variable.

When in doubt about which action to use, run fastlane actions or fastlane search_actions <keyword> to discover the right one.