If you ask any iOS developer, he will most likely tell you that the process of publishing an app is far from simple. Fastlane can dramatically simplify your life by automating all of this. Once configured, one command line will compile your app and send it to iTunes Connect.
What is fastlane?
For me, fastlane is mostly useful for 3 things:
- Automatically synchronize certificates accross your team: you’re starting a job in a new company and you need an Apple Certificate to compile the app on your phone, but first someone has to give you the p12 file to install it (if he’s not on holidays)… Forget about that, thanks to the match tool, all Certificates and Provisioning Profiles will be stored in a private Git repository, and if you don’t have the correct Certificate, it will generate it for you automatically.
- Automatically choose which Provisioning Profile to use: depending on the type of app you want to compile (Development, Ad Hoc, In House or App Store), the match tool will automatically fetch the correct Provisioning Profile, or create or update it if needed. Dead simple! I’ve simply forgot what it’s like to deal with that manually.
- Automatically run the tests, compile your app and send it to TestFlight: thanks to the scan, gym and pilot tools, fastlane will run the tests, compile your app and upload it to TestFlight or any other service provider supported (e.g. Crahlytics) with one single command line.
Fastlane has a lot of other tools but only with those ones, you should already be convinced to use it. See the Actions section below for more informations on how to use them.
Apple has recently changed their servers to require TLS 1.2, which may not be available to your system installed Ruby (2.0.0). So before installing fastlane, start by installing OpenSSL and upgrading your Ruby version to 2.3.1 with Homebrew, which will allow communication with iTunes Connect and the Apple Developer Portal servers.
Open your Terminal and type the following commands:
brew install openssl
brew install ruby
You can finally install fastlane:
sudo gem install fastlane
To initialize fastlane in a project, go into your project directory and type the following command:
Follow the setup assistant, which will set up fastlane for you.
This will prompt you for your Apple ID in order to verify that your application already exists on both iTunes Connect and the Apple Developer Portal. If that’s not the case, fastlane will ask you if it should be created automatically.
This setup will:
- Create a fastlane folder,
- Create fastlane/Appfile, which stores your Apple ID and Bundle Identifier,
- Create fastlane/Fastfile, which stores your lanes.
For more details, please follow the fastlane guide.
The Appfile is used to define a Bundle Identifier. By default there is only one bundle identifer, but you can create one for each lane. You could also specify the app identifier directly in the Fastline file, but it’s more convenient to externalize it in the Appfile.
apple_id "<APPLE_ID>" # Your Apple email address
team_id "<TEAM_ID>" # Developer Portal Team IDfor_platform :ios do
for_lane :test do
end for_lane :beta do
end for_lane :appstore do
By using a different app identifier per lane, you will be able to have different apps on your phone, you could even have different icons for your app.
The Fastfile is the main file used by fastlane, this is where you will configure your lanes with actions.
default_platform :iosplatform :ios do
lane :test do
end lane :beta do
end lane :appstore do
A lane is a collection of actions. In the example above we have 3 lanes:
- test: run all the tests,
- beta: compile an app and send it to TestFlight,
- appstore: submit an app to the App Store.
To launch a lane, you just have to run the following command in the Terminal:
fastlane [os] [lane]
Fastlane provides a lot of actions, you can see the full list here, or by taping the following command-line:
If you want to have a more detailed description of an action, type this:
fastlane action [action_name]
It will list all the parameters available for an action.
Setting up a lane
Most of the time, I use fastlane to send a beta build to TestFlight, here is how I configure my lane:
lane :beta do
# Update Cocoapods
cocoapods # Stop if not on 'develop' branch
ensure_git_branch(branch: "develop") # Fetch Provisioning Profile
) # Run tests on latest iOS version
scan(scheme: "ExampleApp", clean: true) # Increment build number
build_number: latest_testflight_build_number + 1
}) # Compile IPA
gym(scheme: "ExampleApp", configuration: "Beta", clean: true) # Send IPA to TestFlight
pilot(skip_waiting_for_build_processing: true) # Deletes files created during the process (e.g. IPA file)
The actions are quite self-expressive, but I’m gonna explain the important ones.
Match allow you to easily sync your certificates and profiles across your team using Git. The first time you’ll use it, you will be asked for:
- your private Git repository where the Certificates and Provisioning Profiles will be stored,
- the passphrase used to encrypt/decrypt all files on the Git repository.
The type parameter is really important, you can use “development” or “appstore” and it will create a development or production Certificate / Provisioning Profile.
I encourage you to read the Code Signing Guide to learn more about how it works.
Scan makes it easy to run tests of your iOS and Mac app on a simulator or connected device.
Gym allows you to build your app.
The configuration parameter allows me to build the app with a specific app icon.
Pilot makes it easier to manage your app on Apple’s TestFlight, by uploading builds.
Configure Xcode to use fastlane
Since Xcode 8, Apple can automatically manage code signings, I do not use that feature since the match action does it for us, and even stores them in a private repository.
So to make sure fastlane selects the correct Provisioning Profile using match, you have to do a small configuration in the General tab of the Xcode project:
- Disable the “Automatically manage signing” option,
- Manually assign the correct Provisioning Profile for each configuration.
For more information, see the documentation.
Configure fastlane on a new computer
This is where fastlane brings some magic, to configure fastlane on a new computer, you just have to run one lane:
fastlane [os] [lane]
Some passwords may be asked, depending on the actions your lane uses. And that’s all, clean and simple.
I’ve been using fastlane for a few months now, and I couldn’t go back. Even with the new improvements made by Apple, it’s still far from what you can achieve with fastlane.
Trust me, this will save you hours of work, for every app update you release!
Originally published at nicolasbichon.com on August 24, 2016.