Fastlane

A lane is a named, ordered sequence of fastlane actions declared in the Fastfile. CI invokes one by name, such as fastlane ios beta for a lane inside a platform ios block, and the lane's exit status decides the step.

fastlane's build_app action, whose alias is gym, wraps Apple's xcodebuild for iOS: it archives the scheme you name, then exports a signed .ipa plus the archive's dSYM debug-symbol bundles into an output directory.

fastlane captures iOS store screenshots with capture_ios_screenshots, better known as snapshot, which drives an XCUITest on simulators; Android uses capture_android_screenshots, known as screengrab, which drives a separate instrumentation test APK on a device or emulator.

Apple and Google use different credentials. upload_to_app_store takes an App Store Connect API key through api_key or api_key_path; upload_to_play_store takes a Google service-account JSON key through json_key or json_key_data. There is no shared credential model.

before_all runs once before the first lane of a run and before_each before every lane in it. after_each and after_all run only on success, after_all once at the end. error is the single hook that fires when a lane or action raises.

export_method tells fastlane's build_app which Apple distribution channel the export is signed for - app-store, ad-hoc, enterprise or development - and that choice decides which provisioning profile and entitlements are baked into the .ipa.

upload_to_testflight is a core, Apple-only action whose builds wait on Apple's processing before testers can install them. Firebase App Distribution is a third-party plugin that reaches both platforms faster but is a less official channel. Most teams run both.

Stop the guessing and state the mapping: set skip_profile_detection in fastlane's build_app, pin the Apple team with export_team_id, and pass export_options carrying an explicit bundle-identifier-to-profile map, ideally the one sync_code_signing published into the lane context.

match imports the private key into a macOS keychain, so a CI runner needs a dedicated keychain created, unlocked and kept in the search list for the whole build, named to sync_code_signing through keychain_name and keychain_password.

A lane declares a block parameter, conventionally options, which is a hash of the values the caller passed. Command-line callers append key:value pairs after the lane name; a calling lane passes a Ruby hash. Command-line values arrive as strings.

private_lane declares a lane that is not a command-line entry point; only other lanes in the same Fastfile can call it. Use it for shared helper steps so the file's invocable entry points stay few and obvious.

match, whose canonical action name is sync_code_signing, keeps one team's Apple certificates and provisioning profiles in an encrypted shared repository, so every developer machine and CI runner signs the iOS app with the same identity instead of enrolling its own.

fastlane's upload_to_app_store, nicknamed deliver, sends an iOS build and its listing metadata to App Store Connect. upload_to_play_store, nicknamed supply, sends an Android APK or AAB to Google Play. Both spellings work in a Fastfile.

On iOS the changelog is an inline string: upload_to_testflight takes a changelog option, plus localized_build_info for per-language text. Android has no core beta action at all, so release notes ride on the third-party Firebase App Distribution plugin instead.

readonly true makes sync_code_signing only fetch and install existing Apple certificates and profiles, never creating, renewing or revoking any. A CI runner then cannot mint a new certificate, exhaust the team's certificate slots, or write to the shared signing repository.

frame_screenshots, aliased frameit, is pure image post-processing: it reads the PNGs already produced by capture_ios_screenshots on iOS or capture_android_screenshots on Android and writes framed copies, each screenshot composited inside a device bezel with an optional background and title.

On iOS, capture_ios_screenshots takes a languages list and can localize the simulator itself; on Android, capture_android_screenshots takes a locales list plus ending_locale, the locale the shared device is restored to once the capture run finishes.

Uploading an iOS build to TestFlight is not the same as the build being testable: Apple processes it first. Four upload_to_testflight options govern that wait — skip_waiting_for_build_processing, wait_for_uploaded_build, wait_processing_interval and wait_processing_timeout_duration.

Move cleanup out of after_all, which is skipped on failure, into the error hook. Split the long lane into re-runnable lanes that take the artifact path as a parameter, and assert the run's prerequisites in before_all so failures happen early and cheaply.

In fastlane's build_app, derived_data_path places Xcode's intermediates, build_path and archive_path place the .xcarchive, output_directory and output_name place the exported .ipa, buildlog_path saves the raw xcodebuild log, and result_bundle writes the .xcresult.

Regenerate from a machine with write access, never from CI. Run sync_code_signing without readonly and with force to recreate the profiles, or nuke the unusable material first, then let developers and readonly runners sync the new encrypted assets down.

Control three things separately: the machine, the app data and the artifacts. On iOS use erase_simulator, reinstall_app and override_status_bar; on Android use reinstall_app, stable filenames and ending_locale; and on both use clear_previous_screenshots plus launch_arguments to seed fixed data.

Through directories on disk, not return values. Capture writes one folder per locale under output_directory; on Apple, upload_to_app_store reads a separate screenshots_path and metadata_path, while on Google Play upload_to_play_store reads a single metadata_path tree that already contains the images.

On Apple's side upload_to_app_store needs submit_for_review, force to skip the confirmation prompt, and the submission and review information options; automatic_release, auto_release_date and phased_release control the release itself. On Google's side upload_to_play_store needs track, release_status and rollout.

Only when no named option covers it. In fastlane's build_app, xcargs passes raw arguments to Apple's xcodebuild, so prefer validated options such as configuration or sdk, keep project-level settings in an xcconfig, and use export_xcargs for export-only flags.

sync_code_signing supports exactly four storage backends, chosen with storage_mode: git, google_cloud, s3 and gitlab_secure_files. match encrypts the Apple certificates and profiles with OpenSSL before writing, so whichever backend you pick only ever holds ciphertext.

Both read a metadata folder set by metadata_path, but the layouts differ. upload_to_app_store reads a per-locale release_notes entry and also accepts the text inline as an option; upload_to_play_store reads per-locale changelog files named after the Android version code.

On Apple's side upload_to_app_store uses app_version and build_number to choose the App Store Connect version and the build attached to it. On Google's side upload_to_play_store uses version_name and the integer version_code that Play orders releases by.

Pass distribute_only: true to upload_to_testflight. The action then skips the upload entirely and only runs distribution for a build already in TestFlight, identified by app_identifier with app_version and build_number, so no iOS binary is needed.