Fastfile: What It Is, Structure, and Setting Up Automation in Mobile Development

What Is Fastfile and Why You Need It

Fastfile is the main Fastlane configuration file, written in Ruby and placed in the fastlane directory at the project root. It defines all automation scenarios (lanes) for building, testing, code signing, and delivering the application. Fastfile replaces dozens of bash scripts, Makefiles, and manual instructions with a single declarative CI/CD pipeline description.

The need for Fastfile arises when a project requires repeatable builds across different developer machines and CI/CD servers. Instead of each developer setting up the environment manually, Fastfile captures all steps in code that can be versioned in Git, reviewed, and reused across projects. A single Fastfile ensures that the build on a developer's machine is identical to the build on the CI/CD server.

Fastfile supports platforms through the default_platform directive. One Fastfile can describe scenarios for iOS, Android, and macOS, grouping them into platform :ios and platform :android blocks. This is especially useful for cross-platform projects where iOS and Android builds share common deployment logic but use different build tools.

Fastfile Structure: Lanes, Actions, and Parameters

Fastfile consists of three main elements: platform declaration (default_platform), lane definitions, and helper function configuration. Each lane starts with the lane keyword, followed by the scenario name (Ruby symbol), the body with a sequence of actions, and error handling blocks — error, success, or ensure.

Actions in Fastfile are calls to built-in Fastlane functions with parameters as a Hash. For example, gym(scheme: 'App', export_method: 'app-store') triggers an iOS app build with the specified parameters. Each action returns a result that can be stored in a variable and used in subsequent actions — this enables conditional logic inside a lane.

Fastfile supports environment variables through Ruby's standard ENV mechanism. Sensitive data (passwords, tokens, keys) should not be stored in Fastfile — use CI/CD system environment variables or a .env file added to .gitignore. Fastlane automatically loads .env files from the fastlane directory at startup.

Appfile and Matchfile

Additional configuration files are located alongside Fastfile in the fastlane directory. Appfile contains app identifiers (app_identifier), Apple ID, and Team ID — this data is automatically substituted into all actions, eliminating repetition in every lane. Matchfile stores settings for match: the Git repository URL, profile type, and encryption key.

Splitting configuration across multiple files simplifies maintaining projects with different environments. For example, for staging and production, you can create separate branches in the Matchfile repository or override parameters through environment variables in the CI/CD system.

# Basic Fastfile Structure
default_platform(:ios)

lane :build_and_test do
  cocoapods
  scan(scheme: 'App', devices: ['iPhone 15'])
  gym(scheme: 'App')
end

lane :deploy do
  match(type: 'appstore')
  build_and_test
  pilot(skip_waiting_for_build_processing: true)
end

Fastfile Syntax: Writing Lanes

Fastfile syntax is based on Ruby DSL (Domain Specific Language), specifically designed for readability of automation scenarios. A lane is declared using the lane :name do ... end construct, where name is a Ruby symbol that becomes the fastlane name command for running from the terminal or CI/CD system.

Inside a lane, you can use Ruby conditional operators: if, unless, case for branching logic. Loops each and while are also available for processing arrays of values. Fastlane provides special methods before_all, after_all, and error blocks for handling lane lifecycle events.

Lane parameters are passed through the options hash. When running fastlane build --option_name value, the value goes into options[:option_name] inside the lane. You can set default values via optional: true and type validation for controlling the types of passed parameters.

# Lane with parameters and conditional logic
lane :build do |options|
  scheme = options[:scheme] || 'App'
  export_method = options[:export_method] || 'development'

  match(type: export_method)

  if export_method == 'appstore'
    gym(scheme: scheme, export_method: 'app-store')
    pilot(skip_waiting_for_build_processing: true)
  else
    gym(scheme: scheme, export_method: export_method)
  end
end

Fastfile Example for iOS Delivery

A complete Fastfile for an iOS project includes lanes for dependency installation, testing, building, and deploying to TestFlight and the App Store. Let's look at an example that covers a typical CI/CD process from commit to publishing on TestFlight for internal testing.

# Fastfile for iOS CI/CD delivery
default_platform(:ios)

before_all do
  cocoapods(try_repo_update_on_error: true)
  setup_travis if ENV['TRAVIS']
end

lane :tests do
  scan(
    scheme: 'App',
    devices: ['iPhone 15', 'iPad Pro 12.9'],
    output_directory: './test_reports'
  )
end

lane :build_appstore do
  match(type: 'appstore', readonly: true)
  gym(
    scheme: 'App',
    export_method: 'app-store',
    include_bitcode: true
  )
end

lane :deploy_testflight do
  build_appstore
  pilot(
    skip_waiting_for_build_processing: true,
    distribute_external: false
  )
  slack(
    message: 'Build uploaded to TestFlight for internal testing'
  )
end

In this example, the before_all block executes before each lane and installs dependencies. The tests lane runs UI and Unit tests on two devices. The build_appstore lane signs code via match and builds the IPA with bitcode. The deploy_testflight lane combines all steps for complete delivery.

Deployment with Multiple Targets

Projects with multiple targets (main app, watchOS, widget, Notification Service Extension) require separate lanes for each target. In Fastfile, you can create a universal lane :deploy_target that accepts the scheme name and build path as parameters. This allows running deployment for all extensions via fastlane deploy_target scheme:Widget.

To organize multiple targets, use an array of schemes and an each loop inside the lane. Fastlane supports parallel building of multiple schemes through the parallel: true flag, which reduces total CI/CD pipeline time for apps with extensions.

Fastfile Example for Android Build

Fastfile for Android projects uses the gradle action to run Gradle tasks and the supply action for publishing to Google Play. Unlike iOS, Android does not require match, but it uses a Keystore for signing, which is stored outside the repository and passed through environment variables.

# Fastfile for Android CI/CD build
default_platform(:android)

lane :build_release do
  gradle(task: 'clean')
  gradle(task: 'bundleRelease')
  gradle(task: 'assembleRelease')
end

lane :deploy_internal do
  build_release
  supply(
    track: 'internal',
    aab: 'app/build/outputs/bundle/release/app-release.aab',
    release_status: 'completed'
  )
end

For Android app signing, configure signingConfigs in build.gradle and pass Keystore parameters through environment variables: ANDROID_KEYSTORE_PATH, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS, and ANDROID_KEY_PASSWORD. Fastlane automatically uses the system apksigner to sign the built AAB or APK.

Android Signing in Fastfile

To configure Android signing in Fastfile, use the sign_android action or rely on signingConfigs in build.gradle. Fastlane integrates with apksigner through Gradle — passing the SIGNING_CONFIG flag in the gradle task activates signing with parameters from environment variables. This allows signing AAB files before uploading to Google Play Console.

For secure Keystore storage in CI/CD, use Base64 encoding and environment variables. Fastlane supports the setup_keystore action, which decodes the Keystore from a variable and saves it to a temporary file during the before_all stage. After the lane completes, the temporary file is automatically deleted to prevent certificate leakage.

Using Private Lanes and Groups

Private lanes are lanes that cannot be called directly from the command line but are accessible from other lanes inside Fastfile. A private lane is declared using the private_lane :name do ... end construct and is used to encapsulate repetitive steps that do not make sense as standalone scenarios.

Private lanes are ideal for grouping repetitive logic: dependency installation, environment setup, sending notifications. For example, you can create a private lane :setup_signing that is called from several deployment lanes but should not be available for direct execution by a developer to avoid errors.

# Private lane and grouping
default_platform(:ios)

private_lane :setup_signing do |options|
  match(
    type: options[:type],
    readonly: true,
    verbose: false
  )
end

lane :beta do
  setup_signing(type: 'adhoc')
  gym(export_method: 'ad-hoc')
  pilot(distribute_external: true)
end

lane :release do
  setup_signing(type: 'appstore')
  gym(export_method: 'app-store')
  deliver(
    force: true,
    submit_for_review: true
  )
end

Grouping lanes through platform blocks allows separating iOS and Android scenarios in one Fastfile. The platform :ios do ... end and platform :android do ... end constructs isolate lanes for the corresponding platform, while common private lanes can be placed outside platform blocks for reuse.

Passing Parameters to Lanes

The parameters mechanism in Fastfile allows making lanes flexible and reusable. Parameters are passed at runtime through the command line: fastlane build scheme:App export_method:appstore. Inside the lane, values are accessible through the options hash, which is passed to the lane block as an argument.

Fastlane supports typed parameters with validation via OptionalHash. You can specify the value type (String, Boolean, Integer), a default value, and a description for auto-generating documentation. Environment variables are also available as an alternative way to pass parameters, which is convenient for CI/CD systems.

# Parameters with type validation
lane :build do |options|
  gym(
    scheme: options[:scheme],
    export_method: options[:export_method] || 'development',
    include_bitcode: options[:include_bitcode] || false,
    output_name: options[:output_name]
  )
  slack(message: "Build #{options[:scheme]} finished")
end

# Run: fastlane build scheme:MyApp export_method:appstore

It is recommended to use default values for all optional parameters so that a lane can be run without explicitly specifying every argument. For required parameters, check for their presence at the start of the lane and abort execution with a clear error message using UI.user_error!.