Mobile Fastlane

First run on a Mac (checklist)iOS

Last updated 2026-10-07

The iOS lanes are implemented but haven't been run on a Mac yet. Work through this checklist on the first run.

Install these on the Mac first
Xcodelatest (App Store requirement)

Builds and signs the iOS app. macOS only.

Mac App StoreOlder versions (Apple Developer)
xcode-select --install
Verify: xcodebuild -version
Open Xcode once after installing to accept the license and install components.
Homebrewlatest

The macOS package manager used by the other macOS install commands.

brew.sh
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Verify: brew --version
Ruby 3.4 via rbenv3.4.x

Never use the macOS system Ruby; rbenv installs a private Ruby per project.

rbenv install guide
brew install rbenv ruby-build && rbenv install 3.4.1
Verify: ruby --version
Official install guide
CocoaPods≥ 1.13

Installs iOS native dependencies. The framework runs “pod install” for you.

CocoaPods guide
echo 'gem "cocoapods", ">= 1.13"' >> Gemfile && bundle install
Verify: bundle exec pod --version
Node.jsLTS

React Native's Gradle/Xcode build runs Node to bundle JavaScript; also needed for the Firebase CLI.

Download Node.js LTS
winget install OpenJS.NodeJS.LTS
Verify: node --version
Official install guide
Open App Store ConnectOpen App Store Connect API keysOpen Apple Developer account (Team ID)
  1. 1
    Run bundle install and npm ci on the Mac.
  2. 2
    Set ios.enabled: true in environments.yml, or run fastlane init_project.
  3. 3
    In Xcode, make the app scheme Shared (Product → Scheme → Manage Schemes → Shared) and commit xcshareddata.
  4. 4
    In App Store Connect, create the app with your bundle id. Then create an API key (Users and Access → Integrations → App Store Connect API, role Admin for automatic signing).
  5. 5

    Add these to .env:

    .env
    APPLE_TEAM_ID=XXXXXXXXXX
    APP_STORE_CONNECT_KEY_ID=...
    APP_STORE_CONNECT_ISSUER_ID=...
    APP_STORE_CONNECT_KEY_FILE=/absolute/path/AuthKey_XXXX.p8
  6. 6

    Validate and build

    my-app — zsh
    ~/my-app $ bundle exec fastlane ios doctor environment:development
    [09:10:02]: --- iOS Distribution Doctor ---
    [09:10:40]: Pod installation complete! There are 74 dependencies from the Podfile.
    [09:10:41]: Signing method: automatic
    [09:10:41]: Team ID: ABCDE12345
    [09:10:41]: iOS development configuration is valid.
    ~/my-app $ bundle exec fastlane ios build environment:development
    [09:21:13]: Successfully exported and compressed dSYM file
    [09:21:13]: Successfully exported and signed the ipa file:
    [09:21:13]: dist/ios/development/MyApp-development-v1.0.0-12.ipa
    Expected output on the first successful run (Apple's tool output is shortened).
  7. 7
    Run ios distribute. If automatic signing fails, open the project in Xcode once (Signing & Capabilities → select the team), or switch to match.
Known iOS considerations:
  • pod install runs inside the lane, so the workspace doesn't exist until then.
  • The first TestFlight upload needs export-compliance info, or ITSAppUsesNonExemptEncryption in Info.plist (Apple: encryption export regulations).
  • ios build alone also needs the API key, because it prepares signing and the build number.

Official documentation

Was this helpful?
PreviousCode signingNextBuild and upload to TestFlight