Quick guide on fastlane for iOS development

When it comes to publishing an iOS app to the App Store, we need to perform multiple steps like running tests, code signing, archiving and uploading the build, creating screenshots, setting metadata and more. These steps can be very time consuming, especially when publishing on a regular basis.

fastlane is an open source tool that allows you to automate all of these steps and more. At its core, fastlane is a set of Ruby scripts that wrap xcodebuild, the App Store Connect API and more and allow us iOS developers to use commands to automate iOS builds.

Let's see how to do that.

Capture HTTP(s) traffic with Proxyman

Proxyman - Your ultimate man-in-the-middle proxy to effortlessly capture, inspect, and manipulate HTTP(s) traffic on macOS, Windows, iOS, and Android devices.

Get started for free

Installing fastlane

The recommended way to install fastlane for iOS projects is by using Bundler and running bundle init in the root directory of the project. This creates a Gemfile where we can add the following:

source "https://rubygems.org"

gem "fastlane"

After running bundle install, Bundler creates a Gemfile.lock file which clearly defines the fastlane version to be used and its dependencies for the specific iOS project.

To create an initial fastlane setup, we can now run bundle exec fastlane init which creates a fastlane folder including the files Appfile and Fastfile.

Defining and running lanes

From the created files, the most interesting one is fastlane/Fastfile which is a Ruby configuration file we can use to add so called lanes for signing, testing, building, deploying etc.

Each lane is a group of actions. A lane definition looks as follows:

lane :my_lane do
  # fastlane actions
end

Which we can run with the following command:

bundle exec fastlane [lane]

Using fastlane actions

fastlane provides predefined actions for different purposes like running tests, taking screenshots, deploying the app etc. We can combine multiple actions to build a lane, for example:

lane :beta do
  sync_code_signing(type: "appstore")
  build_app(scheme: "ExampleApp")
  upload_to_testflight
  slack(message: "New beta build available.")
end

We'll look at some available actions in more detail later in this article.

Authenticating with Apple services

Several fastlane actions communicate with Apple services that need authentication.

fastlane has historically used Apple IDs with username and password for authentication. Since the announcement of the App Store Connect API at WWDC18, the official and recommended way for authentication is by using the App Store Connect API key. Checkout this guide to learn more on how to generate an API key.

fastlane provides the app_store_connect_api_key action which we can use to generate the key we need for JWT authorization:

api_key = app_store_connect_api_key(
    key_id: "79NWH6F376",
    issuer_id: "69a6de73-ea56-47e3-e053-5b8c7c11a4d1",
    key_filepath: "./AuthKey_79NWH6F376.p8"
)

We can then use the api_key to pass in as a parameter into fastlane actions, for example pilot(api_key: api_key).

Sync certificates and provisioning profiles across the team

For many fastlane actions like deploying to the App Store, a beta testing service or installing the app on a device, a valid certificate and provisioning profile is required.

fastlane provides an action called match which creates all required certificates & provisioning profiles and stores them in a separate Git repository.

Running fastlane match init will create a Matchfile which we can fill out with required properties like Git URL, app identifier etc.:

git_url("https://github.com/tanaschita/exampleAppCertificates")
app_identifier("com.tanaschita.exampleapp")

After doing that, we can run fastlane match appstore or fastlane match development to generate provisioning profiles and certificates and store them in the configured storage.

After successfully setting that up, we can use the match action on our Fastfile to automatically fetch the latest provisioning profiles and certificates:

match(api_key: api_key, type: "appstore")

Running tests

Now, let's look at some actions fastlane provides.

For example, to run tests, we can use fastlane's run_tests action as follows:

lane :tests do
  run_tests(workspace: "ExampleApp.xcworkspace",
            devices: ["iPhone 13 Pro"],
            scheme: "ExampleAppTests")
end

There are various other parameters we can provide such as reset_simulator to automatically erase the simulator before running the iOS application or slack_url to posts results in Slack. To see a full list of parameters, run fastlane action run_tests.

Taking screenshots and uploading screenshots to App Store Connect

To automate the process of taking screenshots with fastlane, we can use its snapshot action which uses the capabilities of UI tests to create the desired application state.

Check out this step-by-step guide on how to setup fastlane's snapshot action.

After creating screenshots, we can use fastlane deliver to upload them to App Store Connect.

Building the application

To build the iOS application, we can use fastlane's build_app action:

build_app(scheme: "ExampleApp")

It creates a ExampleApp.ipa in the current directory.

Uploading to Testflight

Since Testflight is part of App Store Connect, uploading a beta build is just another fastlane action:

upload_to_testflight

fastlane also supports beta deployments to Firebase, HockeyApp and TestFairy.

Uploading to the App Store

Uploading the build to the App Store is also just another fastlane action:

upload_to_app_store

Conclusion

I hope, this guide helped you to get an overview on fastlane which is a powerful tool for automating the development and deployment process for iOS apps. To dive deeper into fastlane, check out their official documentation.

Capture HTTP(s) traffic with Proxyman

Proxyman - Your ultimate man-in-the-middle proxy to effortlessly capture, inspect, and manipulate HTTP(s) traffic on macOS, Windows, iOS, and Android devices.

Get started for free