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
The files
Fastfile | lanes in Ruby; its code runs in ./fastlane, actions + plugins in the project root |
Appfile | app_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 |
Pluginfile | gem "fastlane-plugin-x" lines, pulled in by the Gemfile’s eval_gemfile |
| generated | README.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
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;descfeedsfastlane lanesand the README; aprivate_laneis hidden and callable only from another lane.- A lane call is a method call:
build(release: true); last expression = return value;nextleaves early andafter_each/after_allstill run. before_all/after_allonce;before_each/after_eacharound every lane, called ones too;erroron any raise.lane_context[SharedValues::…]chains actions:upload_to_testflightdefaultsipatoIPA_OUTPUT_PATHand the key toAPP_STORE_CONNECT_API_KEY.- Plugins are gems (
fastlane add_plugin x) — third-party code on the signing machine: pin and review.fastlane action gymlists 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 |
s3 | encrypted unless s3_skip_encryption |
google_cloud | not encrypted by match — Google-managed keys; bucket IAM is the lock |
gitlab_secure_files | not encrypted by match — GitLab project access is the lock |
| v1 | Salted__ · 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(distributionservesappstoreandadhoc) ·profiles/appstore/AppStore_<bundle>.mobileprovision; portal namematch AppStore <bundle>.security import -T /usr/bin/codesignintokeychain_name(defaultlogin.keychain, on CIsetup_ci’s), thenset-key-partition-list -S apple-tool:,apple:,codesign:— signing without a UI prompt.- Profiles go to
~/Library/Developer/Xcode/UserData/Provisioning Profilesfor 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_MAPPINGfor gym,SIGH_PROFILE_TYPEas gym’s defaultexport_method. readonlyfetches only ·force_for_new_devicesrenews when the portal’s device count changed ·change_password·import(existing.cer/.p12) ·migrate(storage → storage) ·nuke distributionrevokes + deletes: App Store / TestFlight builds keep working, Ad Hoc and Enterprise builds stop.
Auth — API key vs Apple ID
| ASC API key | Key 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 ID | FASTLANE_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 (orvalidate_only). A commit or a Play Console change invalidates every other open edit — serialise jobs. trackproduction(default),beta,alpha,internal;release_statuscompleted(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.cioverrides the CI secret of the same name. -showBuildSettingstimes out on big projects (3 s × 3):FASTLANE_XCODEBUILD_SETTINGS_TIMEOUT.export_methodtakes onlyapp-store,ad-hoc…; Xcode 15.4+ logs them as deprecated (app-store-connect,release-testing).- pilot’s
apple_idis the app’s numeric id, not the Appfile’s e-mail;skip_waiting_for_build_processing→ nothing is distributed.