This guide will walk you through how to setup Fastlane, with special focus on the ‘Match’ tool which automates the handling of code-signing for iOS apps.

A Full List of All of Fastlane’s Tools:

• deliver: Upload screenshots, metadata, and your app to the App Store
• supply: Upload your Android app and its metadata to Google Play
• snapshot: Automate taking localized screenshots of your iOS and tvOS apps on every device
• screengrab: Automate taking localized screenshots of your Android app on every device
• frameit: Quickly put your screenshots into the right device frames
• pem: Automatically generate and renew your push notification profiles
• sigh: Because you would rather spend your time building stuff than fighting provisioning
• produce: Create new iOS apps on iTunes Connect and Dev Portal using the command line
• cert: Automatically create and maintain iOS code signing certificates
• spaceship: Ruby library to access the Apple Dev Center and iTunes Connect
• pilot: The best way to manage your TestFlight testers and builds from your terminal
• boarding: The easiest way to invite your TestFlight beta testers
• gym: Building your iOS apps has never been easier
• match: Easily sync your certificates and profiles across your team using Git
• scan: The easiest way to run tests for your iOS and Mac apps

Setting up Fastlane

1. Install Fastlane

brew cask install fastlane

Gemfile

gem 'fastlane'

bundle install

2. Run `fastlane init`

bundle exec fastlane init
 
# `fastlane help` && `fastlane actions` will give you some helpful info

`fastlane init` will prompt you for various info, asking if you want to use certain tools, and storing the info you input into files. It will create a directory called ‘fastlane’ in your root directory, and a file named ‘Appfile’. Most Fastlane tools have a corresponding configs file named after the tool, ie. Matchfile, Gymfile, etc. You can generate these files which contain helpful comments by running init commands like:

bundle exec fastlane match init
bundle exec fastlane gym init
 
# and so on. Each tool also has a help page:
bundle exec fastlane match help

The ‘Appfile’ contains info that is universal to all the things you want to do with Fastlane. For instance, you would probably specify your apple_id and app_identifier/bundle_id in it like so:

fastlane/Appfile

apple_id 'metovadev@metova.com'
app_identifier 'com.metova.MyBundleID' 

If you setup the above, all the Fastlane tools should know what your apple_id and app_identifier is.

3. Setup your Fastfile

Running `fastlane init` will also create a ‘fastfile’, which is a ruby file that defines all your ‘lanes’. A lane is a set of instructions you want Fastlane to run.
Here’s an example of what a fastfile might look like:

fastlane/Fastfile

default_platform :ios
 
platform :ios do
  lane :develop do
    produce(itc_team_id: '1643054')
    match(type: development)
    gym(configuration: 'Development') 
  end
 
  lane :release do |options|
    match
    gym(clean: true, silent: options[:silent])
  end
end

You can run a lane by calling the fastlane command followed by the name of the lane:

bundle exec fastlane develop
 
# you can also pass in config options via command line:
bundle exec fastlane develop --verbose true
 
# furthermore, you can pass in key:value pairs if you want to use them in your lane
# notice the 'options' variable being passed into the release lane
bundle exec fastlane release silent:true

Produce is a tool that can create an app id in dev center and ITC (iTunes Connect). If it already exists, it won’t do anything.

Gym is a wrapper for xcodebuild. It gathers most of what it needs to know from your project, but you can pass in options easily in the command itself or in your Gymfile.

Match will generate all the code-signing files you need, encrypt them, and store them in a repo you designate. This is arguably the most powerful tool (although snapshot seems pretty amazing), so the rest of the guide will focus on Match.

Setting up Match

1. Create a repo on GitLab to store your certs

Match uses another Fastlane tool call ‘Sigh’ to generate certs and provisioning profiles, and then automatically encrypts them and stores them in a repo. This is a huge benefit because none of the certs will be stored on your local machine. No more emailing p12s around to other developers, or forgetting where you stored that .mobileprovision profile. If you would rather not store the certs in a repo, you can always just use Sigh directly.

2. Once you’ve created a repo to store the certs, run match init

bundle exec fastlane match init

Fastlane will ask you for a password to use to encrypt and decrypt the repo. I recommend you generate a secure random password and hang on to it somewhere. If you lose that, you’ll be in bad shape. Also, anyone who has the password has access to all your certs! There are benefits to this though, because now any developer on your team can generate certs using Fastlane if they access to the repo.

3. Set up your Matchfile

A Matchfile might look as simple as something like this:

fastlane/Matchfile
git_url 'git@lab.metova2018.wpengine.com:metova/my-project-certificates.git'
shallow_clone true         # because I don't need the whole git history of the certs
force_for_new_devices true # if someone adds a device I want to make sure they can test the app

You can set all of these configs with environment variables in your Matchfile or Fastfile as well, and Fastlane will automatically use them. So you could do something like:

fastlane/Matchfile

ENV['MATCH_APP_IDENTIFIER'] = com.metova.myproject
git_url 'git@lab.metova2018.wpengine.com:metova/my-project-certificates.git'
shallow_clone true
force_for_new_devices true

Then have access to that in your Fastfile:

fastlane/Fastfile

...
  lane :release do
    puts "Running release lane for app: #{ENV['MATCH_APP_IDENTIFIER']}"
    match
... 

These are all the possible configs you could use with match. You can always see the list with `fastlane match help`

git_url 'git@lab.metova2018.wpengine.com:metova/my-project-certificates.git' # STRING URL - the git repo containing all the certificates - ENV['MATCH_GIT_URL']
git_branch                                                      # STRING - Specific git branch to use - ENV['MATCH_GIT_BRANCH']
type 'distribution'                                             # STRING - Create a development certificate instead of a distribution one - ENV['MATCH_TYPE']
app_identifier com.metova.myproject                             # [VALUE] - The bundle identifier(s) of your app (comma-separated) - ENV['MATCH_APP_IDENTIFIER']
username 'metova.apple@metova.com'                              # STRING - Your Apple ID Username - ENV['MATCH_USERNAME']
keychain_name 'mykeychain'                                      # STRING - Keychain the items should be imported to - ENV['MATCH_KEYCHAIN_NAME']
keychain_password 'mypassword'                                  # STRING - This might be required the first time you access certificates on a new mac. 
                                                                # For the login/default keychain this is your account password - ENV['MATCH_KEYCHAIN_PASSWORD']
readonly false                                                  # [VALUE] - Only fetch existing certificates and profiles, don't generate new ones - ENV['MATCH_READONLY']
team_id '325SDF345'                                             # STRING - The ID of your Developer Portal team if you're in multiple teams - ENV['FASTLANE_TEAM_ID']
team_name "My Project's Apple Team"                             # STRING - The name of your Developer Portal team if you're in multiple teams - ENV['FASTLANE_TEAM_NAME']
verbose false                                                   # [VALUE] - Print out extra information and all commands - ENV['MATCH_VERBOSE']
force false                                                     # [VALUE] - Renew the provisioning profiles every time you run match - ENV['MATCH_FORCE']
skip_confirmation false                                         # [VALUE] - Disables confirmation prompts during nuke, answering them with yes - ENV['MATCH_SKIP_CONFIRMATION']
shallow_clone true                                              # [VALUE] - Make a shallow clone of the repository (truncate the history to 1 revision) - ENV['MATCH_SHALLOW_CLONE']
force_for_new_devices true                                      # [VALUE] - Renew the provisioning profiles if the device count on the developer portal has changed - ENV['MATCH_FORCE_FOR_NEW_DEVICES']
skip_docs false                                                 # [VALUE] - Skip generation of a README.md for the created git repository - ENV['MATCH_SKIP_DOCS']

You can also run Match (as well as other tools) straight from the command line. You can pass in the above configs just by prepending ‘–’ before the config name like:

bundle exec fastlane match appstore --shallow_clone false --verbose true

References

https://fastlane.tools/
https://docs.fastlane.tools/
https://github.com/fastlane/fastlane

CONTACT US