New to fastlane? Click here to open the installation & setup instructions first

1) Install the latest Xcode command line tools

xcode-select --install

2) Install fastlane

# Using RubyGems
sudo gem install fastlane -NV

# Alternatively using Homebrew
brew cask install fastlane

3) Navigate to your project and run

fastlane init

More Details


Other advanced topics that didn't fit anywhere else:

Environment Variables

You can define environment variables in a .env or .env.default file in the same directory as your Fastfile. Environment variables are loaded using dotenv. Here's an example:


fastlane also has a --env option that allows loading of environment specific dotenv files. .env and .env.default will be loaded before environment specific dotenv files are loaded. The naming convention for environment specific dotenv files is .env.<environment>

For example, fastlane <lane-name> --env development will load .env, .env.default, and .env.development

Alternatively, as environment variables are not a fastlane specific thing, you can also use standard methods to set them:

DELIVER_USER="" fastlane test


export DELIVER_USER="";
fastlane test

Although it kind of defeats the purpose of using them in the first place (not to have their content in any files), you can also set them in your Fastfile:


Adding Credentials

You can add credentials for use by fastlane to your keychain using the CredentialsManager command line interface. This is useful for situations like CI environments.

Adding a Credential

fastlane fastlane-credentials add --username
Password: *********
Credential********* added to keychain.

Removing a Credential

fastlane fastlane-credentials remove --username
password has been deleted.

Manually manage the fastlane match Repo

Most users can benefit from match's automatic management of the repo that stores certificates and provisioning profiles. From time to time, it may be necessary to manually change the files in this repo.

For example, fastlane requires admin access to the Apple Developer account to generate the appropriate files. If you are provided with an updated certificate or profile but do not have admin access, you can manually edit the repo.

Warning: Manually editing your match repo can introduce unexpected behavior and is not recommended. Proceed with caution.




  1. fastlane encrypts the repo, and
  2. fastlane doesn't support manual edits to the repo

it's necessary to manually decrypt, then modify, then encrypt, the repo to make any changes.

These instructions presuppose you already have fastlane match configured correctly.

🔓 Decryption Instructions

The easiest way to decrypt the repo is to use the fastlane match Storage and Encryption classes. You can do this from an interactive Ruby console:

$ bundle console

Then, require match and set the appropriate parameters:

irb(main):001:0> require 'match'
irb(main):002:0> git_url = ''
=> ""
irb(main):003:0> shallow_clone = false
=> false
irb(main):004:0> ENV["MATCH_PASSWORD"] = 'example-password'
=> "example-password"
irb(main):005:0> branch = 'master'
=> "master"

Now create an instance of Storage and Encryption. The download method on Storage will clone the repo and the decrypt_files method on Encryption will decrypt the repo for you. Assign the return values to storage and encrypt, which we'll need later when we re-encrypt:

irb(main):006:0> storage = Match::Storage.for_mode("git", { git_url: git_url, shallow_clone: shallow_clone, git_branch: branch, clone_branch_directly: false})
irb(main):008:0> encryption = Match::Encryption.for_storage_mode("git", { git_url: git_url, working_directory: storage.working_directory})
irb(main):009:0> encryption.decrypt_files
[14:24:42]: 🔓  Successfully decrypted certificates repo
irb(main):010:0> storage.working_directory
=> "/var/folders/ql/4rgq9x7j51n_971xb332w9lc0000gn/T/d20181105-65220-1oalh6v"

The above example checks out the master (which is the default branch that match uses). A common match pattern is to create a separate branch per each developer team (the name of the branch being the team identifier).

The directory beginning with /var/folders contains the decrypted git repo. Modify it as needed.

If you are updating a .p12 file, ensure it's exported from the keychain without a password, since match doesn't support importing private keys with a password.

Warning: Do not commit your changes. Allow fastlane to do that for you.

Once your changes are made, we'll need to encrypt the repo and push it.

🔒 Encryption Instructions

In the Ruby console, call encryption.encrypt and storage.save_changes!. For example:

irb(main):010:0> encryption.encrypt_files
irb(main):011:0> files_to_commit = Dir[File.join(storage.working_directory, "**", "*.{cer,p12,mobileprovision}")]
irb(main):012:0> storage.save_changes!(files_to_commit: files_to_commit)

Your changes will be encrypted, committed, and pushed.

Note: If your keychain doesn't include the encryption passcode, you may be prompted for it. If so, just enter the same password you used to decrypt it.