fastlane Tutorial: Getting Started

In this fastlane tutorial, you’ll learn how to provision, screenshot, build and upload an app to the App Store using fastlane. By Lyndsey Scott.

Leave a rating/review
Download materials
Save for later
Share
Update note: Lyndsey Scott updated this tutorial for Xcode 10.1, Swift 4.2, Ruby 2.5.1 and fastlane 2.112.0. Satraj Bambra wrote the original.

It’s that wonderful moment: You’ve poured days, weeks or maybe even months into building an app, and it’s finally ready to share with the world. All you have to do is submit it to the App Store. How hard could that be, right?

Cue mountains of grunt work: capturing tons of screenshots, adding your app to the Apple Developer and App Store Connect sites, uploading your binary and metadata and other mindless work! Argh!

Isn’t there a better way? If only you could run a single command that took all your screenshots on all your supported devices, in every supported language automagically. If only there were a single command to upload those screenshots, add your app to Apple’s developer sites and submit it all. Think of all the time you’d save!

Well, you’re in luck. :] Thanks to creator Felix Krause and lead maintainer Josh Holtz, there’s a tool to do all this and more! It’s called fastlane! In this tutorial, you’ll learn how to use fastlane to deploy an app to the App Store. It’s sure to become your new best friend. Even Google’s buddied up with fastlane by acquiring it in 2017.

If sticks were screenshots, this dog would be nearly as helpful as fastlane.

fastlane tutorial

If sticks were screenshots, this dog would be nearly as helpful as fastlane.

Note: This tutorial assumes that you have a paid Apple Developer account, as well as a basic knowledge of the command line, Xcode and the app submission process. If you don’t have an account, this tutorial will help you.

Getting Started

First, download the materials for this tutorial at the top or bottom of this page using the Download Materials button, then save them to a convenient location.

This tutorial’s sample app, mZone Poker, is a poker calculator for No Limit Texas Hold ‘Em tournaments. It displays a recommended action based on your chip count and the current big blind level.

Open the mZone project in Xcode to build, run and check it out.

mZone starter

Setting Up fastlane

The tool fastlane is a collection of Ruby scripts, so you must have the correct version of Ruby installed. Chances are that your OS comes with Ruby 2.0 by default, but you can confirm whether this is the case by opening Terminal and entering:

ruby -v

If it’s not installed, the easiest way to do so is via Homebrew a package manager for macOS.

Install Homebrew by entering this Terminal command:

/usr/bin/ruby -e \
  "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Then, install Ruby using:

brew update && brew install ruby

Run brew link --overwrite ruby and/or open a new Terminal session if Homebrew instructs you to do so.

You’ll also need Xcode Command Line Tools (CLT). To ensure that they’re installed, enter into Terminal:

xcode-select --install

If Xcode CLT are already installed, you will get this error: xcode-select: error: command line tools are already installed, use "Software Update" to install updates. If not, continue the installation when prompted.

Now you’re ready to install fastlane! Enter the following command to do so:

sudo gem install -n /usr/local/bin fastlane --verbose

If you prefer to use Homebrew enter the following command:

brew cask install fastlane
Note: With El Capitan, OS X introduced System Integrity Protection, also known as Rootless, which prevents users from having root access. /usr/local/bin is still writable, which is why you’re installing fastlane there.

After entering your system password, you will see a bunch of activity in Terminal indicating that the installation is in progress. This could take a few minutes, so grab some coffee, walk your dog or brush up on your zombie-fighting tactics. :]

Once installation completes, you’re ready to set up fastlane in your project. But before you do, here’s a high-level look at the fastlane tools.

The fastlane Toolchain

To work its magic, fastlane brings the following set of tools all under one roof:

  • produce creates new iOS apps in both App Store Connect and the Apple Developer Portal.
  • cert automatically creates and maintains iOS code-signing certificates.
  • sigh creates, renews, downloads and repairs provisioning profiles.
  • snapshot automates taking localized screenshots of your iOS app on every device.
  • frameit puts your screenshots into the right device frames.
  • gym builds and packages your iOS apps.
  • deliver uploads screenshots, metadata and your apps to the App Store.
  • pem automatically generates and renews your push notification profiles.
  • spaceship is a Ruby library able to access the Apple Developer Center and App Store Connect APIs.
  • pilot automates TestFlight deployments and manages beta testers.
  • boarding invites beta testers.
  • match syncs certificates and provisioning profiles across your team, using Git.
  • scan runs tests on your apps.

You’ll use several of these tools today. Enough with the theory for now — it’s time to put this tutorial into gear and enter the fast lane!

Adding fastlane to Your Project

Open Terminal and cd into your mZone starter project. For example, if you’ve added the mZone_Sample_Project folder to your desktop, you can enter:

cd ~/Desktop/mZone_Sample_Project/mZone

To set the mZone starter project as the working directory.

Next, enter:

fastlane init

To initialize fastlane.

If at any point, fastlane tells you to update to a newer version, but running sudo gem update fastlane outputs that there is “Nothing to update,” perhaps the Ruby manager you’re using isn’t up to date. Run gem sources --add https://rubygems.org/ to install Ruby Gems since it’s likely to produce the most current information.

Notes: If you get a “permission denied” error, prefix this command with sudo.

If at any point, fastlane tells you to update to a newer version, but running sudo gem update fastlane outputs that there is “Nothing to update,” perhaps the Ruby manager you’re using isn’t up to date. Run gem sources --add https://rubygems.org/ to install Ruby Gems since it’s likely to produce the most current information.

After some output, fastlane will ask: “What would you like to use fastlane for?”

fastlane init output

output fast lane init

fastlane init output

Although fastlane “recommend[s] automating one task first,” you’ll implement multiple automated actions during this single tutorial, so input 4 to commence manual setup. Read the output and press Enter when prompted.

Back in the mZone folder, you’ll see a few new things: Gemfile, which includes the fastlane gem as a project dependency and a fastlane folder containing:

  • Appfile: stores the app identifier, your Apple ID and any other identifying information that fastlane needs to set up your app.
  • Fastfile: manages the lanes you’ll create to invoke fastlane actions.

generated files

Open Fastfile in a text editor of your choice, disable smart quotes if your text editor supports them, then replace the contents of the file with:

default_platform(:ios)

platform :ios do
# 1
  desc "Create app on Apple Developer and App Store Connect sites"
# 2
  lane :create_app do
# 3
​    produce
  end
end

If you’ve never seen Ruby before, this may look like gibberish to you. Here’s what this code does:

  1. Provides a description for the lane. (A lane is a workflow of sequential tasks).
  2. Names this lane create_app.
  3. Uses produce to add the app to both the Developer Portal and App Store Connect.

Woohoo! You have now created your very first lane.

panda

Save Fastfile, then open Appfile. Remove the pound (#) sign to uncomment the line starting with apple_id, then replace [[APPLE_ID]] with your actual Apple ID username. By setting this information now, fastlane won’t have to repeatedly prompt you for it later on.

Then replace each username placeholder with its respective username.

Note: If your App Store Connect and Apple Developer Portal usernames are different, replace the apple_id line with:
apple_dev_portal_id("[[APPLE_DEVELOPER_ACCOUNT_USERNAME]]")
itunes_connect_id("[[APP_STORE_CONNECT_ACCOUNT_USERNAME]]")

Then replace each username placeholder with its respective username.

apple_dev_portal_id("[[APPLE_DEVELOPER_ACCOUNT_USERNAME]]")
itunes_connect_id("[[APP_STORE_CONNECT_ACCOUNT_USERNAME]]")

Save Appfile before closing.