fastlane

iOS/macOS app automation — builds, signing, TestFlight, App Store via CLI

# 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

```bash
fastlane --version
```

If not installed:

```bash
brew install fastlane
```

Or via RubyGems:

```bash
sudo gem install fastlane -NV
```

After install, add to your shell profile:

```bash
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](https://appstoreconnect.apple.com/access/api).
2. Download the `.p8` file.
3. Set environment variables:

```bash
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:

```bash
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

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

Generate an app-specific password at [appleid.apple.com](https://appleid.apple.com). If 2FA is enabled, you may also need:

```bash
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

| Variable | Purpose |
|---|---|
| `APP_STORE_CONNECT_API_KEY_KEY_ID` | API key ID from App Store Connect |
| `APP_STORE_CONNECT_API_KEY_ISSUER_ID` | Issuer ID from App Store Connect |
| `APP_STORE_CONNECT_API_KEY_KEY_FILEPATH` | Path to the `.p8` private key file |
| `APP_STORE_CONNECT_API_KEY_KEY` | Inline JSON containing all key fields |
| `FASTLANE_USER` | Apple ID email |
| `FASTLANE_PASSWORD` | Apple ID password or app-specific password |
| `FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD` | App-specific password for 2FA accounts |
| `MATCH_PASSWORD` | Encryption password for match certificates repo |
| `MATCH_GIT_URL` | Git URL for match certificates repository |

---

## One-Off Action Execution

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

```bash
fastlane run <action_name> key:value key2:value2
```

Discover available actions:

```bash
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

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

Equivalent:

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

With API key:

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

### List Builds

```bash
fastlane pilot builds
```

### Manage Testers

```bash
# 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

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

### Common pilot Flags

| Flag | Purpose |
|---|---|
| `--ipa` | Path to IPA file |
| `--app_identifier` | Bundle ID (e.g., `com.example.app`) |
| `--skip_waiting_for_build_processing` | Don't wait for Apple's processing |
| `--distribute_external` | Send to external testers |
| `--groups` | Tester group names (comma-separated) |
| `--changelog` | What to Test text |
| `--beta_app_review_info` | JSON with review info |

---

## deliver (App Store)

### Submit to App Store

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

Equivalent:

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

### Upload Metadata Only

```bash
fastlane deliver --skip_binary_upload --skip_screenshots
```

### Upload Screenshots Only

```bash
fastlane deliver --skip_binary_upload --skip_metadata
```

### Download Existing Metadata

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

### Download Existing Screenshots

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

### Common deliver Flags

| Flag | Purpose |
|---|---|
| `--ipa` | Path to IPA file |
| `--pkg` | Path to PKG file (macOS) |
| `--app_identifier` | Bundle ID |
| `--submit_for_review` | Auto-submit after upload |
| `--automatic_release` | Release automatically after approval |
| `--force` | Skip HTML preview verification |
| `--skip_binary_upload` | Metadata/screenshots only |
| `--skip_metadata` | Binary/screenshots only |
| `--skip_screenshots` | Binary/metadata only |
| `--metadata_path` | Custom metadata folder path |
| `--screenshots_path` | Custom screenshots folder path |
| `--phased_release` | Enable phased release |
| `--reject_if_possible` | Reject current version before uploading |

---

## gym / build_app (Build)

### Build an IPA

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

Equivalent:

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

### Build with Xcode Project (no workspace)

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

### Export Methods

| Method | Use Case |
|---|---|
| `app-store` | App Store and TestFlight submission |
| `ad-hoc` | Direct device installation via profile |
| `development` | Debug builds for registered devices |
| `enterprise` | In-house enterprise distribution |
| `developer-id` | macOS distribution outside App Store |
| `mac-application` | macOS App Store |
| `validation` | Validate without exporting |

### Common gym Flags

| Flag | Purpose |
|---|---|
| `--workspace` | Path to `.xcworkspace` |
| `--project` | Path to `.xcodeproj` |
| `--scheme` | Build scheme |
| `--configuration` | Build config (Debug/Release) |
| `--export_method` | See export methods table |
| `--output_directory` | Where to save the IPA |
| `--output_name` | Custom IPA filename |
| `--clean` | Clean before building |
| `--include_bitcode` | Include bitcode |
| `--include_symbols` | Include dSYM symbols |
| `--xcargs` | Extra xcodebuild arguments |
| `--derived_data_path` | Custom DerivedData path |
| `--catalyst_platform` | `macos` or `ios` for Catalyst apps |

> **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

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

Equivalent:

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

### Sync for Development

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

### Sync for Ad Hoc

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

### Read-Only Mode (CI)

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

> **Agent guidance:** Always use `--readonly`