Use case: fastlane and fastlane Match on Bitrise

Learn how to use fastlane and fastlane Match to manage iOS code signing for multiple apps at a scale 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.

How fastlane match works

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 
Copy code

Alternatively, you can install fastlane using Homebrew: 

 brew install fastlane 
Copy code

Initialize fastlane in your project

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

 fastlane init 
Copy code

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 
Copy code

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 
Copy code

App Store Certificates and Profiles:

 fastlane match appstore 
Copy code

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

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

You can then run this lane using the following command:

 fastlane development 
Copy code

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 
Copy code

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 
Copy code

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

No items found.
The Mobile DevOps Newsletter

Explore more topics

App Development

Learn how to optimize your mobile app deployment processes for iOS, Android, Flutter, ReactNative, and more

Bitrise & Community

Check out the latest from Bitrise and the community. Learn about the upcoming mobile events, employee spotlights, women in tech, and more

Bitrise Insights

Cache | Caching

Mobile App Releases

Learn how to release faster, better apps on the App Store, Google Play Store, Huawei AppGallery, and other app stores

Mobile DevOps

Learn Mobile DevOps best practices such as DevOps for iOS, Android, and industry-specific DevOps tips for mobile engineers

Mobile Testing & Security

Learn how to optimize mobile testing and security — from automated security checks to robust mobile testing and more.

Product Updates

Check out the latest product updates from Bitrise — Build Insights updates, product news, and more.

The Mobile DevOps Newsletter

Join 1000s of your peers. Sign up to receive Mobile DevOps tips, news, and best practice guides once every two weeks.