# fastlane-ios-distribution

> Automate iOS distribution with Fastlane for TestFlight beta delivery and App Store releases. Use when setting up `fastlane/` in an Xcode project, creating or editing lanes (e.g. `beta`, `release`, `appstore`), configuring App Store Connect API keys / signing, uploading builds via `pilot` / `upload_to_testflight`, submitting releases via `deliver` / `upload_to_app_store`, or debugging common Fastlane build/signing/upload failures in CI.

- Author: Barron Roth
- Repository: barronlroth/fastlane-ios-distribution
- Version: 20251221185820
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/barronlroth/fastlane-ios-distribution
- Web: https://mule.run/skillshub/@@barronlroth/fastlane-ios-distribution~fastlane-ios-distribution:20251221185820

---

---
name: fastlane-ios-distribution
description: Automate iOS distribution with Fastlane for TestFlight beta delivery and App Store releases. Use when setting up `fastlane/` in an Xcode project, creating or editing lanes (e.g. `beta`, `release`, `appstore`), configuring App Store Connect API keys / signing, uploading builds via `pilot` / `upload_to_testflight`, submitting releases via `deliver` / `upload_to_app_store`, or debugging common Fastlane build/signing/upload failures in CI.
---

# Fastlane iOS Distribution

## Workflow decision tree

1. If the repo already has `fastlane/Fastfile`, prefer using existing lanes first.
2. If the repo has a `Gemfile`, run Fastlane via Bundler: `bundle exec fastlane <lane>`.
3. If there is no `fastlane/`, create it with `fastlane init` and add lanes for:
   - **Beta** (TestFlight): build + upload via `pilot`/`upload_to_testflight`
   - **Release** (App Store): build + upload/submit via `deliver`/`upload_to_app_store`

## Quick start

- Run the bundled repo check script (prints what to run next):
  - `bash ${CODEX_HOME:-~/.codex}/skills/fastlane-ios-distribution/scripts/fastlane_doctor.sh`
- List lanes: `bundle exec fastlane lanes` (or `fastlane lanes` if not using Bundler).
- Run a lane:
  - TestFlight: `bundle exec fastlane beta`
  - App Store: `bundle exec fastlane appstore` or `bundle exec fastlane release`

## Credentials and secrets

Prefer **App Store Connect API keys** for CI (non-interactive).

Common env vars to support:
- `APP_STORE_CONNECT_API_KEY_KEY_ID`
- `APP_STORE_CONNECT_API_KEY_ISSUER_ID`
- One of:
  - `APP_STORE_CONNECT_API_KEY_KEYFILE_PATH` (points to a `.p8` file on disk), or
  - `APP_STORE_CONNECT_API_KEY_KEY_CONTENT_BASE64` (base64-encoded `.p8` contents)

Never commit `.p8` keys to git; store them in CI secrets.

## Beta (TestFlight) lane checklist

For a typical iOS beta lane:
1. Increment build number (optional; depends on your versioning strategy).
2. Build an App Store export (`build_app`) for the correct scheme.
3. Upload to TestFlight (`upload_to_testflight`).

See `references/ios-beta.md` for a minimal lane skeleton and common options.

## App Store lane checklist

For an App Store release lane:
1. Ensure version/build matches what you intend to ship.
2. Build an App Store export.
3. Upload the build and (optionally) submit for review (`upload_to_app_store`).
4. Upload metadata/screenshots if you manage them via Fastlane (`deliver`).

See `references/ios-appstore.md`.

## Best practices (short list)

- Pin toolchain: use Bundler (`Gemfile`) and run `bundle exec fastlane ...`.
- Set `FASTLANE_SKIP_UPDATE_CHECK=1` in CI.
- Keep lanes deterministic (avoid interactive prompts in CI).
- Prefer API keys over Apple ID login for CI.

See `references/best-practices.md` and `references/troubleshooting.md`.

## Resources

### scripts/
- `scripts/fastlane_doctor.sh`: quick repo check + next-step hints

### references/
- `references/ios-beta.md`: beta/TestFlight lane notes
- `references/ios-appstore.md`: App Store lane notes
- `references/best-practices.md`: CI + repo hygiene
- `references/troubleshooting.md`: common failures and fixes