fastlane — config, lanes, match internals, store auth

cicd · folio

In one line: fastlane is a Ruby gem (pin it with Bundler) whose lanes call actions; gym, scan, pilot, deliver, snapshot, match, supply wrap xcodebuild, Apple’s upload tools, the App Store Connect API and the Google Play Developer API. On CI its job is to make signing and upload non-interactive: match decrypts one shared cert/profile store into a throw-away keychain, and an API key (.p8) replaces an Apple ID that needs 2FA.

Download PDF Print view LaTeX source

fastlane — config, lanes, match internals, store auth — figure 1

The files

Fastfilelanes in Ruby; its code runs in ./fastlane, actions + plugins in the project root
Appfileapp_identifier, apple_id (account e-mail), team_id, itc_team_id; Android: json_key_file, package_name
Matchfile Gymfile …per-tool defaults, found in ./fastlane, ./.fastlane or .; the first value set wins unless inside for_lane / for_platform
Gemfile(.lock)both committed; bundle exec fastlane; upgrade with bundle update fastlane
Pluginfilegem "fastlane-plugin-x" lines, pulled in by the Gemfile’s eval_gemfile
generatedREADME.md (lane descs; FASTLANE_SKIP_DOCS), report.xml (JUnit of the actions) — git-ignore with Preview.html, screenshots, test_output

Where an option’s value comes from

fastlane — config, lanes, match internals, store auth — figure 2

CLI fastlane ios beta n:5 dry:yes → options[:n] == "5": only true/yes, false/no are converted; numbers stay strings.

Lanes

  • platform :ios do → fastlane ios beta; desc feeds fastlane lanes and the README; a private_lane is hidden and callable only from another lane.
  • A lane call is a method call: build(release: true); last expression = return value; next leaves early and after_each/after_all still run.
  • before_all/after_all once; before_each/after_each around every lane, called ones too; error on any raise.
  • lane_context[SharedValues::…] chains actions: upload_to_testflight defaults ipa to IPA_OUTPUT_PATH and the key to APP_STORE_CONNECT_API_KEY.
  • Plugins are gems (fastlane add_plugin x) — third-party code on the signing machine: pin and review. fastlane action gym lists every option and its env name.

Tool ↔ action

gym=build_app · scan=run_tests · pilot=upload_to_testflight · deliver=upload_to_app_store · snapshot=capture_ios_screenshots · precheck=check_app_store_metadata · match=sync_code_signing · cert=get_certificates · sigh=get_provisioning_profile · supply=upload_to_play_store. Deprecated: xcversion → xcodes; automatic_code_signing → update_code_signing_settings. precheck runs inside deliver before submit at level warn: placeholder text, other platforms, unreachable URLs.

Example — Fastfile

before_all { setup_ci }          # no-op unless a CI env var is set
platform :ios do
  lane :beta do
    app_store_connect_api_key(key_id: ENV["ASC_KEY_ID"],
      issuer_id: ENV["ASC_ISSUER_ID"], key_content: ENV["ASC_P8_B64"],
      is_key_content_base64: true)     # -> lane_context
    match(type: "appstore", readonly: true)
    increment_build_number(build_number: latest_testflight_build_number + 1)
    build_app(scheme: "App", export_method: "app-store")
    upload_to_testflight(skip_waiting_for_build_processing: true)
  end
end

increment_build_number runs agvtool new-version -all <n>; with no n, next-version — which needs Apple Generic versioning. An empty train returns initial_build_number (1).

match — storage and encryption

git (default)encrypted with MATCH_PASSWORD; branch master, one branch per team; auth git_basic_authorization (base64), _bearer_, git_private_key
s3encrypted unless s3_skip_encryption
google_cloudnot encrypted by match — Google-managed keys; bucket IAM is the lock
gitlab_secure_filesnot encrypted by match — GitLab project access is the lock
v1Salted__ · AES-256-CBC · key + IV from one MD5 round (SHA-256 retried) — a wrong password went undetected ∼0.4 % of the time
v2 (2.220.0+)match_encrypted_v2__ · AES-256-GCM + tag · PBKDF2-HMAC-SHA256, 10 000 rounds, 8-byte salt. Older fastlane cannot read it: force_legacy_encryption. The docs’ openssl aes-256-cbc recipe opens v1 only; fastlane match decrypt opens both

match — what it writes and installs

  • certs/<type>/<cert-id>.cer + .p12 (distribution serves appstore and adhoc) · profiles/appstore/AppStore_<bundle>.mobileprovision; portal name match AppStore <bundle>.
  • security import -T /usr/bin/codesign into keychain_name (default login.keychain, on CI setup_ci’s), then set-key-partition-list -S apple-tool:,apple:,codesign: — signing without a UI prompt.
  • Profiles go to ~/Library/Developer/Xcode/UserData/Provisioning Profiles for Xcode ≥ 16 (~/Library/MobileDevice/… before; right only since 2.230.0) — select Xcode (xcodes) before match.
  • Sets ENV["sigh_<bundle>_appstore"] = profile UUID (+ _profile-name, _team-id …), MATCH_PROVISIONING_PROFILE_MAPPING for gym, SIGH_PROFILE_TYPE as gym’s default export_method.
  • readonly fetches only · force_for_new_devices renews when the portal’s device count changed · change_password · import (existing .cer/.p12) · migrate (storage → storage) · nuke distribution revokes + deletes: App Store / TestFlight builds keep working, Ad Hoc and Enterprise builds stop.

Auth — API key vs Apple ID

ASC API keyKey ID + Issuer ID + .p8 (downloadable once). Team key: an Admin makes it, role-scoped, all apps. Individual key: no Provisioning, Sales and Finance or notaryTool — match, sigh, cert need a team key. Apple rejects tokens >20 min for most requests (scoped GET-only tokens on a few resources: up to 6 months). Works for pilot, deliver, match, sigh, cert, precheck (not IAP); not pem
Apple IDFASTLANE_USER + password + 2FA; fastlane spaceauth → FASTLANE_SESSION, valid 1 day – 1 month and only in the region it was made — make it on the CI machine. An app-specific password covers binary upload only. It drives Apple’s web sign-in: 2.240.0 had to re-find the sign-in widget key after Apple dropped its endpoint

supply — Google Play

  • Service-account JSON (json_key / _data). One run = one Play Developer API edit: insert → upload AAB → track → listing → commit (or validate_only). A commit or a Play Console change invalidates every other open edit — serialise jobs.
  • track production (default), beta, alpha, internal; release_status completed (default), draft, halted, inProgress; rollout: 0.1 → inProgress + userFraction, rollout: 1 → completed.

Traps

  • sh("ls") runs in ./fastlane, actions in the root — relative paths differ.
  • No bundle exec = the global fastlane; plugins may not load.
  • A committed .env.ci overrides the CI secret of the same name.
  • -showBuildSettings times out on big projects (3 s × 3): FASTLANE_XCODEBUILD_SETTINGS_TIMEOUT.
  • export_method takes only app-store, ad-hoc …; Xcode 15.4+ logs them as deprecated (app-store-connect, release-testing).
  • pilot’s apple_id is the app’s numeric id, not the Appfile’s e-mail; skip_waiting_for_build_processing → nothing is distributed.

Report a problem ·Discuss this folio