Simplify you life with fastlane

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?

Fastlane is a free set of tools created by Felix Krause that automate building and releasing your iOS apps.

For me, fastlane is mostly useful for 3 things:

  1. Automatically synchronize certificates across 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.
  2. 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 forgotten what it’s like to deal with that manually.
  3. 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. Crashlytics) 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 information on how to use them.

Requirements

Apple has recently changed its 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 update

brew install openssl

brew install ruby

Configuration

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:

fastlane init

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.

Appfile

The Appfile is used to define a Bundle Identifier. By default, there is only one bundle identifier, 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 ID

for_platform :ios do
    for_lane :test do
        app_identifier "com.nicolasbichon.exampleapp.test"
    end

    for_lane :beta do
        app_identifier "com.nicolasbichon.exampleapp.beta"
    end

    for_lane :appstore do
        app_identifier "com.nicolasbichon.exampleapp"
    end
end

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.

Fastfile

The Fastfile is the main file used by fastlane, this is where you will configure your lanes with actions.

default_platform :ios

platform :ios do
    lane :test do
        # Actions
    end

    lane :beta do
        # Actions
    end

    lane :appstore do
        # Actions
    end
end

Lanes

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]

Actions

Fastlane provides a lot of actions, you can see the full list here, or by taping the following command-line:

fastlane actions

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
    match(
        git_url: "https://github.com/TakeEatEasy/ios-codesigning",
        type: "appstore"
    )

    # Run tests on latest iOS version
    scan(scheme: "ExampleApp", clean: true)

    # Increment build number
    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)
    clean_build_artifacts
end

The actions are quite self-expressive, but I’m gonna explain the important ones.

match

Match allows 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

Scan makes it easy to run tests of your iOS and Mac app on a simulator or connected device.

gym

Gym allows you to build your app.

The configuration parameter allows me to build the app with a specific app icon.

pilot

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.

Conclusion

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!

← Back to articles