Chapters
Chapters

Chapters

Hide chapters

iOS App Distribution & Best Practices

Before You Begin

Section 0: 6 chapters
Show chapters Hide chapters

Section I: iOS App Distribution & Best Practices

Section 1: 17 chapters
Show chapters Hide chapters

Section II: Appendices

Section 2: 2 chapters
Show chapters Hide chapters

13. Introduction to Fastlane
Written by Pietro Rea & Keegan Rush

Heads up... You're reading this book for free, with parts of this chapter shown beyond this point as scrambled text.

You can unlock the rest of this book, and our entire catalogue of books and videos, with a Kodeco Personal subscription.

Unlock now

Using xcodebuild and the App Store Connect API to build and manage your app can be a lot of work. Isn’t extra work what you were trying to get away from by using automation? :]

Well, you don’t necessarily need to interact with xcodebuild yourself. There’s a collection of open-source tools that interact the Xcode toolchain and the App Store Connect API, so you don’t have to.

There are some alternatives, but the most popular approach to automating iOS builds is through the use of fastlane.

At its core, fastlane is a collection of Ruby scripts that make build automation easy and accessible to iOS developers. It’s a collection of tools that wrap xcodebuild, the App Store Connect API and more:

  • cert creates and maintains your signing certificates.
  • sigh handles provisioning profiles.
  • gym builds, signs and packages apps.
  • deliver uploads apps, metadata and screenshots to App Store Connect.
  • pilot uploads builds for TestFlight and handles its administration.
  • scan runs your project’s automated tests.

Those are just a few of fastlane’s many actions.

Even when all you have is a superb idea for an app, fastlane can help to streamline your development process – it can even:

  • Create an app record on App Store Connect.
  • Manage the entire code signing process by creating provisioning profiles and signing certificates.
  • Create push notification certificates.
  • Take screenshots across different devices and across different languages, saving hours spent taking marketing screenshots.

If that’s not enough, fastlane also comes with a rich plugin system for you to create any action your heart desires, and share it with other users.

It’s because of all this that the iOS community has accepted fastlane as the go-to approach for build automation.

Next up, as a first step to working with fastlane, you’ll add some simple build automation for Emitron:

  1. Run unit tests with scan.
  2. If no tests fail, prepare for code signing with cert and sigh.
  3. Build Emitron for the App Store with gym.
  4. Upload Emitron to TestFlight with pilot.
  5. Upload builds for App Store review with deliver.

Strap yourself in; it’s time to start living life in the fastlane! :]

Getting started

In this chapter, you’ll be working with fastlane to upload builds to App Store Connect. To do so, you’ll need to make sure that the starter project’s app record, provisioning profile and signing certificate are correctly set up.

Note: To learn more about provisioning profiles, or if you need a refresher on configuring them, refer to Chapter 4, “Code Signing & Provisioning”.

To configure the starter project, refer back to the Setting up the starter project section in Chapter 12, “Build Automation”.

Note: The bundle identifier that you use for Emitron on App Store Connect should be the same as the one used throughout the book: com.raywenderlich.emitron.pias.

Once all of that’s done, you’re ready to install fastlane.

Installing fastlane

Once you’ve finished setting up your app record, provisioning profile and signing certificate, you’ll need to get fastlane working on your computer.

sudo gem install bundler

touch Gemfile

source "https://rubygems.org"

gem "fastlane"

bundle update

Setting up fastlane

Without setting up fastlane in a specific project, it’s about as useful as an empty build script. To start using fastlane, you need to give it some information about your project.

bundle exec fastlane init

Building Emitron

Before worrying about uploading Emitron to App Store Connect for TestFlight or the App Store, you’ll first use fastlane to automate a simple build. You’ll gain familiarity in configuring a project for an automated build using fastlane.

# 1
ENV["FASTLANE_XCODEBUILD_SETTINGS_TIMEOUT"] = "600"
# 2
default_platform(:ios)
# 3
platform :ios do
  # 4
  lane :build do
    scan
  end
end

fastlane build

Configuring scan

In fastlane’s current state, there are no explicit directions on how scan should test Emitron.

scan(scheme: "Emitron", clean: true)

fastlane scan init


# 1
scheme("Emitron")
# 2
device("iPhone 12 Pro")

fastlane build

Signing and building

From code signing to app archiving, the process is infamous for causing developers headaches. You can use fastlane can automate that minus the headaches.

cert
sigh
gym

Configuring code signing

cert and sigh both need a bit more context to function. Each of them takes their configuration from Appfile, the configuration file for project metadata.

app_identifier("com.raywenderlich.emitron.pias")
apple_id("keeganrush@gmail.com")
itc_team_name("Keegan Rush")
team_id("MC7X4Q9BS6")

Configuring gym

To hand off the iOS apps build and package processes to fastlane, you’ll use gym. Integrating gym into your automation flow makes generating a signed ipa a breeze. gym uses the cert and sigh configurations you’ve setup earlier to sign your ipa.

fastlane gym init


# 1
scheme("Emitron")
# 2
clean(true)
# 3
output_directory("./")
# 4
export_method("app-store")

Running the completed lane

With the actions you added, the build lane will now:

fastlane build


ls

Uploading to App Store Connect

When uploading to App Store Connect, you can choose to upload an app specifically for TestFlight or App Store review. To upload archived apps for their respective purposes, you’ll create two new lanes: alpha lane using Emitron’s alpha build and release lane using Emitron’s release build.

Creating the alpha lane

In Fastfile, add the following after the end of the build lane:

lane :alpha do
  # 1
  build
  # 2
  pilot
  # 3
  increment_build_number
end

Incrementing the build number

When uploading a build to App Store Connect, one particular error plagues developers more than any other. If you happened to forget to change your app’s build version, you’ll be greeted with a familiar Redundant Binary Upload error.

Setting up increment_build_number

Fastlane can’t automatically bump your build number without changing how your project’s versioning works.

Creating an app-specific password

If you want to upload an iOS app to App Store Connect from outside of Xcode or xcodebuild, you’ll need to generate an app-specific password. Rather than signing in with your Apple Developer account’s usual username and password, any tools that need access to your developer account must sign in using an app-specific password. If you don’t have one, and try to use your Apple ID’s regular password instead, pilot will fail when trying to upload Emitron!

Running the alpha lane

To upload a new build to TestFlight, all you need to do is to run the alpha lane.

fastlane alpha

Creating the release lane

To upload a release build of Emitron, you’ll make a new lane similar to alpha.

lane :release do
  # 1
  build
  # 2
  deliver
  # 3
  increment_build_number
end

Configuring deliver

In the terminal, run the following:

fastlane deliver init


# 1
skip_metadata(true)
# 2
skip_screenshots(true)
# 3
force(true)

Running the release lane

In the terminal, run your new release lane:

fastlane release

More on fastlane

In this chapter, you’ve come a long way: from being restricted to manual builds in Xcode to an automated build pipeline with fastlane.

Key points

  • Fastlane acts as a wrapper for xcodebuild and the App Store Connect API.
  • Fastlane can be broken down into a structure of platforms, lanes and actions.
  • By using the vast variety of actions, fastlane can streamline your entire build process and make other project setups much easier.
  • Most fastlane actions are configurable using one of fastlane’s various configuration files.
12. Build Automation
14. Continuous Integration
Have a technical question? Want to report a bug? You can ask questions and report bugs to the book authors in our official book forum here.
© 2023 Kodeco Inc.

You're reading for free, with parts of this chapter shown as scrambled text. Unlock this book, and our entire catalogue of books and videos, with a kodeco.com Professional subscription.

Unlock now

Access this book

To highlight or take notes, you'll need to own this book in a subscription or purchased by itself.

Read for Free with a Subscription

Buy this book for $59.99