fastlane Tutorial: Getting Started

Note: This tutorial has been updated for Xcode 8.2, Swift 3 and Fastlane 2.6.0 by Lyndsey Scott. The original tutorial was written by Satraj Bambra.

It’s that wonderful moment: You’ve poured days, weeks, or maybe even months into building an amazing 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, fighting Xcode provisioning, uploading to the App Store and constant mindless work! Aargh!

Wouldn’t it be nice if there was 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, generate your provisioning profiles and submit your app. Think of all the time you’d save!

Well, you’re in luck. :] Thanks to the amazing Felix Krause, there’s now a tool to do all this and more! It’s called fastlane, and it’ll become your new best friend.

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

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

In this fastlane tutorial, you’ll learn how to use fastlane to deploy an app to the App Store. You’re in for a fast ride, so buckle up and hang on tight!

Note: This tutorial uses the command line extensively. While you don’t need to be a Terminal expert, you’ll need to have basic knowledge for how the command line works.

This tutorial also assumes you know about code signing and iTunes Connect. If you’re unfamiliar with these, please read this tutorial series first.

Getting Started

Download the starter project here, and save it to a convenient location.

mZone, the sample app you’ll use in this tutorial, is a simple 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 project in Xcode to see the app yourself, then navigate to the mZone Poker target’s Build Settings. In the Product Bundle Identifier field, you’ll find com.mZone.mZone-Poker-xxx:

Replace “xxx” with your email address sans “@” and “.” so that the bundle identifier for your project is different from every other app identifier on iTunes Connect.

To get fastlane up and running the following are required:

• OS X 10.9 (Mavericks) or newer
• Ruby 2.0 or newer
• Xcode Command Line Tools (CLT)
• Paid Apple Developer Account

Since fastlane is a collection of Ruby scripts, you must have the correct version of Ruby installed. Fortunately, OS X 10.9 (Mavericks) and later come with Ruby 2.0 by default. You can confirm this by opening Terminal and entering the following command:

ruby -v

To check whether the Xcode CLT are installed, enter the following into Terminal:

xcode-select --install

If Xcode CLT are already installed, you will get this error: command line tools are already installed, use "Software Update" to install updates. If not, it will install Xcode CLT for you.

With the prerequisites completed, you’re ready to install fastlane. Enter the following command:

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

After entering your system password, you will see a bunch of activity in your Terminal window, indicating 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. :]

When the installation completes, you’ll be ready to set up your project to use fastlane. But before you do, let’s take 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 iTunes 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 iTunes 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 will be using many of these tools in the deployment process of the sample app.

That’s enough theory– it’s time to put fastlane in the fast lane!

Setting up fastlane

First, open Terminal and cd into your mZone project location. For example, if you’ve added the mZone folder to your desktop, you can enter:

cd ~/Desktop/mZone

to set mZone as the working directory.

Once you are in the mZone folder, enter the following command:

fastlane init

Note: If you get a “permission denied” error, you will need to prefix this command with sudo.

Next, enter your Apple ID to kickstart the process.

fastlane uses deliver to sign you into both iTunes Connect and the Apple Developer Portal, and it also verifies an app exists in your account with a matching app identifier. Since this is a new app, it won’t exist, and it will need to be created.

try updating your ruby version as fastlane suggests to do.

Unless you’re already using rbenv or rvm (which are Ruby version managers), the easiest way to do this is via Homebrew.

First, install Homebrew by entering this Terminal command:

Next, install Ruby using the `brew` command:

Homebrew might also tell you that you need to run brew link --overwrite ruby. You may also need to open a new Terminal session. Then, install fastlane again without specifying an install path:

Lastly, run fastlane init again, and it should be able to create the app on iTunes Connect.

Connection reset by peer - SSL_Connect

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

brew update && brew install ruby

sudo gem install fastlane --verbose

Connection reset by peer - SSL_Connect

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

brew update && brew install ruby

sudo gem install fastlane --verbose

You should see the following output:

This app identifier doesn't exist on iTunes Connect yet, it will be created for you
This app identifier doesn't exist on the Apple Developer Portal yet, it will be created for you
Please confirm the above values (y/n)

Enter “y” to confirm the detected values.

Since I’ve already created an app called “mZone Poker” on iTunes Connect, you’ll next be prompted:

It looks like that mZone Poker has already been taken by someone else, please enter an alternative App Name:

Type in a unique app name. (Similar to my recommendation for the bundle ID, I recommend “mZone Poker” followed by your email address sans “@” and “.” to ensure the app name is unique.)

After some time (as little as 30 seconds and as much as 30 minutes depending on the emotional state of Apple’s occasionally volatile servers), you’ll be informed that your app was created on iTunes Connect.

Open the mZone project folder. You will notice that your project now has a fastlane folder:

The relevant files are:

• Appfile, which stores the app identifier and your Apple ID.
• Fastfile, which manages the lanes you create to call certain actions.
• Deliverfile, which lets you add the required metadata when submitting your app to the App Store.

Within the mZone Project folder, navigate to fastlane\metadata. You will notice a bunch of text files there that contain common App Store items like the description, keywords, categories, etc. These files are used to set your app’s metadata information displayed on the App Store.

Open en-US/description.txt and add the following text:

mZone is a simple poker calculator for No Limit Texas Hold’em tournaments that displays a recommended course of action based on your chip count and the current big blind level.

Add the following to keywords.txt:

Poker, Cards, Gambling

Check that name.txt already contains the name of your app, then type http://www.raywenderlich.com into both privacy_url.txt and support_url.txt.

While this app supports both French and English, only the en-US folder exists.

To fix this, simply make a copy of the folder and call it fr-FR. In the interests of keeping this fastlane tutorial shorter, we won’t actually provide real French translations now. Your project folder should now look like this:

Next, in the metadata folder:

• Add Copyright (c) 2016 Razeware LLC to copyright.txt
• Add Games to primary_category.txt
• Add Card to primary_first_sub_category.txt
• Add Casino to primary_second_sub_category.txt

Then, in the same folder, use your favorite text/code editor to create a json file named itunes_rating_config.json containing the following:

{
  "CARTOON_FANTASY_VIOLENCE": 0,
  "REALISTIC_VIOLENCE": 0,
  "PROLONGED_GRAPHIC_SADISTIC_REALISTIC_VIOLENCE": 0,
  "PROFANITY_CRUDE_HUMOR": 0,
  "MATURE_SUGGESTIVE": 0,
  "HORROR": 0,
  "MEDICAL_TREATMENT_INFO": 0,
  "ALCOHOL_TOBACCO_DRUGS": 0,
  "GAMBLING": 2,
  "SEXUAL_CONTENT_NUDITY": 0,
  "GRAPHIC_SEXUAL_CONTENT_NUDITY": 0,
  "UNRESTRICTED_WEB_ACCESS": 0,
  "GAMBLING_CONTESTS": 0
}

This iTunes rating configuration lets iTunes Connect know that out of all the ratings criteria, the app only contains “frequent/intense” simulated gambling (i.e. value = 2). This file gives iTunes Connect the information it requires to give the app the age rating Apple has deemed appropriate.

And lastly, download the App Store icon here and also add it to the metadata directory.

Congratulations! You’ve added all the metadata required for submission. It’s time to to start using fastlane. :]