xcode-select --install

# Using RubyGems
sudo gem install fastlane -NV

# Alternatively using Homebrew
brew install fastlane

fastlane init

Lanes

Passing Parameters

To pass parameters from the command line to your lane, use the following syntax:

fastlane [lane] key:value key2:value2

fastlane deploy submit:false build_number:24

To access those values, change your lane declaration to also include |options|

before_all do |lane, options|
  # ...
end

before_each do |lane, options|
  # ...
end

lane :deploy do |options|
  # ...
  if options[:submit]
    # Only when submit is true
  end
  # ...
  increment_build_number(build_number: options[:build_number])
  # ...
end

after_all do |lane, options|
  # ...
end

after_each do |lane, options|
  # ...
end

error do |lane, exception, options|
  if options[:debug]
    puts "Hi :)"
  end
end

Switching lanes

To switch lanes while executing a lane, use the following code:

lane :deploy do |options|
  # ...
  build(release: true) # that's the important bit
  hockey
  # ...
end

lane :staging do |options|
  # ...
  build # it also works when you don't pass parameters
  hockey
  # ...
end

lane :build do |options|
  build_config = (options[:release] ? "Release" : "Staging")
  build_ios_app(configuration: build_config)
end

fastlane takes care of all the magic for you. You can call lanes of the same platform or a general lane outside of the platform definition.

Passing parameters is optional.

Returning values

Additionally, you can retrieve the return value. In Ruby, the last line of the lane definition is the return value. Here is an example:

lane :deploy do |options|
  value = calculate(value: 3)
  puts value # => 5
end

lane :calculate do |options|
  # ...
  2 + options[:value] # the last line will always be the return value
end

Stop executing a lane early

The next keyword can be used to stop executing a lane before it reaches the end.

lane :build do |options|
  if cached_build_available?
    UI.important 'Skipping build because a cached build is available!'
    next # skip doing the rest of this lane
  end
  match
  gym
end

private_lane :cached_build_available? do |options|
  # ...
  true
end

When next is used during a lane switch, control returns to the previous lane that was executing.

lane :first_lane do |options|
  puts "If you run: `fastlane first_lane`"
  puts "You'll see this!"
  second_lane
  puts "As well as this!"
end

private_lane :second_lane do |options|
  next
  puts "This won't be shown"
end

When you stop executing a lane early with next, any after_each and after_all blocks you have will still trigger as usual :+1:

before_each and after_each blocks

before_each blocks are called before any lane is called. This would include being called before each lane you've switched to.

before_each do |lane, options|
  # ...
end

after_each blocks are called after any lane is called. This would include being called after each lane you've switched to. Just like after_all, after_each is not called if an error occurs. The error block should be used in this case.

after_each do |lane, options|
  # ...
end

e.g. With this scenario, before_each and after_each would be called 4 times: before the deploy lane, before the switch to archive, sign, and upload, and after each of these lanes as well.

lane :deploy do
  archive
  sign
  upload
end

lane :archive do
  # ...
end

lane :sign do
  # ...
end

lane :upload do
  # ...
end

Lane Context

The different actions can communicate with each other using a shared hash. You can access this in your code (lanes, actions, plugins etc.):

lane_context[SharedValues::VARIABLE_NAME_HERE]

Here are some examples:

lane_context[SharedValues::BUILD_NUMBER]                # Generated by `increment_build_number`
lane_context[SharedValues::VERSION_NUMBER]              # Generated by `increment_version_number`
lane_context[SharedValues::SNAPSHOT_SCREENSHOTS_PATH]   # Generated by _snapshot_
lane_context[SharedValues::PRODUCE_APPLE_ID]            # The Apple ID of the newly created app
lane_context[SharedValues::IPA_OUTPUT_PATH]             # Generated by _gym_
lane_context[SharedValues::DSYM_OUTPUT_PATH]            # Generated by _gym_
lane_context[SharedValues::SIGH_PROFILE_PATH]           # Generated by _sigh_
lane_context[SharedValues::SIGH_UDID]                   # The UDID of the generated provisioning profile
lane_context[SharedValues::HOCKEY_DOWNLOAD_LINK]        # Generated by `hockey`
lane_context[SharedValues::GRADLE_APK_OUTPUT_PATH]      # Generated by `gradle`
lane_context[SharedValues::GRADLE_ALL_APK_OUTPUT_PATHS] # Generated by `gradle`
lane_context[SharedValues::GRADLE_FLAVOR]               # Generated by `gradle`
lane_context[SharedValues::GRADLE_BUILD_TYPE]           # Generated by `gradle`

To get information about available lane variables, run fastlane action [action_name] or look at the generated table in the action documentation.

Lane Properties

It can be useful to dynamically access some properties of the current lane. These are available in lane_context as well:

lane_context[SharedValues::PLATFORM_NAME]        # Platform name, e.g. `:ios`, `:android` or empty (for root level lanes)
lane_context[SharedValues::LANE_NAME]            # The name of the current lane preceded by the platform name (stays the same when switching lanes)
lane_context[SharedValues::DEFAULT_PLATFORM]     # Default platform

They are also available as environment variables:

ENV["FASTLANE_PLATFORM_NAME"]
ENV["FASTLANE_LANE_NAME"]

Private lanes

Sometimes you might have a lane that is used from different lanes, for example:

lane :production do
  # ...
  build(release: true)
  appstore # Deploy to the AppStore
  # ...
end

lane :beta do
  # ...
  build(release: false)
  crashlytics # Distribute to testers
  # ...
end

lane :build do |options|
  # ...
  ipa
  # ...
end

It probably doesn't make sense to execute the build lane directly using fastlane build. You can hide this lane using

private_lane :build do |options|
  # ...
end

This will hide the lane from:

• fastlane lanes
• fastlane list
• fastlane docs

And also, you can't call the private lane using fastlane build.

The resulting private lane can only be called from another lane using the lane switching technology.

Control configuration by lane and by platform

In general, configuration files take only the first value given for a particular configuration item. That means that for an Appfile like the following:

app_identifier "com.used.id"
app_identifier "com.ignored.id"

the app_identifier will be "com.used.id" and the second value will be ignored. The for_lane and for_platform configuration blocks provide a limited exception to this rule.

All configuration files (Appfile, Matchfile, Screengrabfile, etc.) can use for_lane and for_platform blocks to control (and override) configuration values for those circumstances.

for_lane blocks will be called when the name of lane invoked on the command line matches the one specified by the block. So, given a Screengrabfile like:

locales ['en-US', 'fr-FR', 'ja-JP']

for_lane :screenshots_english_only do
  locales ['en-US']
end

for_lane :screenshots_french_only do
  locales ['fr-FR']
end

locales will have the values ['en-US', 'fr-FR', 'ja-JP'] by default, but will only have one value when running the fastlane screenshots_english_only or fastlane screenshots_french_only.

for_platform gives you similar control based on the platform for which you have invoked fastlane. So, for an Appfile configured like:

app_identifier "com.default.id"

for_lane :enterprise do
  app_identifier "com.forlane.enterprise"
end

for_platform :mac do
  app_identifier "com.forplatform.mac"

  for_lane :release do
    app_identifier "com.forplatform.mac.forlane.release"
  end
end

you can expect the app_identifier to equal "com.forplatform.mac.forlane.release" when invoking fastlane mac release.