Use case: fastlane and fastlane Match on Bitrise

Customers can use fastlane and fastlane Match on Bitrise to manage code signing for multiple apps at scale.

• Platform: Bitrise
• Use case: The customer needs to use fastlane Match to manage code signing for +40 apps at scale

iOS certificates and provisioning profiles for large mobile teams

When developing iOS apps, each app must be signed with a unique certificate and provisioning profile in order to be deployed to devices and to the App Store. In a large mobile team, it's important to manage these certificates and profiles in a centralized and secure way, in order to avoid conflicts and ensure that everyone on the team is using the same, up-to-date files.

What is fastlane Match?

One way to manage certificates and profiles in a large team is to use a tool called fastlane match. This tool allows developers to securely store their signing certificates and provisioning profiles in a Git repository, and to automatically download the latest versions of these files when building and releasing apps.

The Matchfile in the repository would specify which files should be stored and how they should be accessed. Then, when a team member needs to build and release an app, they can use match to download the latest versions of the necessary certificates and profiles.

With the Fastlane Match Step, Bitrise takes care of the code signing process for you, by cloning your private certificate/profile repository and registering those certificates and profiles in the keychain.

Configuring fastlane Match for a project

First, install the fastlane tools on your computer and navigate to your iOS project directory in the Terminal.

Fastlane can be installed using RubyGems, which is a package manager for the Ruby programming language. To install Fastlane, run the following command:

gem install fastlane 

Alternatively, you can install fastlane using Homebrew: 

brew install fastlane

Initialize fastlane in your project

Navigate to your project's root directory and run the following command: 

fastlane init

This will create a Fastfile in your project, which is a configuration file for fastlane

Initialize fastlane Match

fastlane Match is a tool that can be used to manage and sync your certificates and provisioning profiles across your team. It is part of the fastlane suite of tools, which are designed to make it easier to automate the development and release process for iOS and Android apps. 

To set up fastlane Match, you will need to create a private Git repository to store your signing assets. 

After you have initialized the repository, you can use the match command to import your existing certificates and profiles or to generate new ones. You can then use the match command to export these files to the other members of your team and to update them whenever they change. fastlane Match uses encryption to protect your files, so you can safely store them in a shared repository like GitHub.

Initialize a new fastlane Match repository for your project by running the following command:

fastlane match init

This will create a Matchfile in your project and local Git repository where your certificates and profiles will be stored, which you can use to configure the distribution of your signing assets.

In the Matchfile, you need to update the following:

• The git_url
• The app_identifier
• The username (your Apple Developer email address)

Note: fastlane Match supports different storage options such as Google Cloud Storage and Amazon S3

Set up your signing certificates and provisioning profiles

To set up your signing certificates and provisioning profiles, you will need to create a new lane in your Fastfile that uses the match action. This lane should specify the type of signing assets you want to create or maintain (e.g., development, AppStore, adhoc, etc.).

You can use the match command to import your existing certificates and profiles or to generate new ones. For instance, you might run the following command to generate a new distribution certificate and profile:

Development Certs and Profiles:

fastlane match development

App Store Certificates and Profiles:

fastlane match appstore

Or create a new development signing certificate and provisioning profile from the Fastfile, using the following lane:

lane :development do
  match(type: "development")
end

You can then run this lane using the following command:

fastlane development

Use the match command to export your certificates and profiles to the other members of your team. For example, you might run the following command to push your files to a remote Git repository like GitHub:

fastlane match git_push

When you or another member of your team makes changes to your certificates or profiles, use the match command to update the local and remote copies. For example, you might run the following command to pull the latest changes from the remote repository and update your local copy:

fastlane match git_pull

Once you have created and distributed your signing assets, you will need to configure your Xcode project to use them. To do this, open your project in Xcode and navigate to the "Signing & Capabilities" tab. Select the correct signing certificate and provisioning profile from the dropdown menus. Additionally, make sure that Automatic Code Signing is disabled.

You should now be able to build and deploy your iOS app using Fastlane and Fastlane Match.

Run Fastlane Match on Bitrise

These instructions assume that you have an iOS app configured on Bitrise. If you’re not there yet, you can follow these steps. 

• Add the Fastlane Match step to your workflow before you build your app.

‍

• Add your Team ID and Match Decrypt Password created when running fastlane init as a Secret on Bitrise.

• Configure the Fastlane Match step with your Git URL, branch, App ID, Match Password, Platform, and Team ID

• Run your build and make sure your Fastlane Match step is run before your Xcode Archive Step for code signing to work

Related resources

• iOS code signing
• Integrating fastlane to Bitrise
• Fastlane documentation
• Bitrise-Fastlane-Match-Sample on GitHub