Integrate Fastlane to iOS project: Lesson 6

Integrate with Fastlane Match

Last lesson, we use .env file to store the environment parameters so that our Fastfile are more easy to read the workflow.

This lesson, we will talk about Fastlane Match, which is a service provided by Fastlane to manage your iOS certificates and provisioning profiles.

What is Fastlane Match?

Match is designed to manager your project code sign (both certificates and provisioning profiles) across your whole team. It saves your time and avoid the troubles to manage the annoying certificates and provisioning profile sync issue.

Let’s think about the following situation.

A new team, John, member joins your team. After he installed the Xcode and needed information, he needs to build the app to his iPhone. Therefore, your team needs to do the following actions

• John creates a new development certificates.
• John adds a new iOS devices to the devices list.
• John creates a new development and distribution provisioning profiles.
• You and your team members download the latest development and distribution provisioning profile.

This practise will introduce the following problems.

• hard to know which provisioning profile is using if there is not a good naming convention for your certificates and provisioning profile.
• all the team members need to prefer the same action every time if a new team member who join your project. It wastes time !!
• different certificates has different expiry day, all the team members have to work on the steps every year.
• find the .p12 in your one of your Macbook in order to pass the certificates from someone to anther one

How Fastlane Match can solve this problem?

Match helps you to store the valid certificates and provisioning profile to a separate repository. It use the specified certificates and provisioning profile in your Matchfile when you build and archive your app.

Installation Guide

In order to integrate Match to your existing iOS project, it requires 2 things:

1. a new git repository, used to store the valid iOS certificates and provisioning profile
2. a share iOS developer account, actually this is an optional, but I strongly recommend your team has a share developer account. It helps you to work on DevOps more easily.

Go to your project directory in Terminal and run

fastlane match init

It will ask you to enter the git repo URL. After that, a Matchfile is created under your /fastlane folder. Matchfile is similar to Fastfile, it purposes to manage the certificates and provisioning profile setting.

Open your Matchfile, it will show as following.

git_url("<your_url>")  
app_identifier("<your_app_id>") 
username("<share_apple_developer_account>")

Run fastlane match development and go to your Apple Developer account. You will find Match has created the development certificates and development provisioning profile for you. The provisioning profile file prefix is match Development xxx.

Check your certificates git repo, it will have a new commit in there. Open the file, you will see the following

There are Development folder under certs folder and profiles folder. This is because we just create the development type development cert and provisioning profile.

Open your Xcode, go to your Target general tab, untick the Automatically manage signing, update the signing (Debug) to your new provisioning profile and run the project.

Now, your project will use the new certificates and provisioning profile to run the project. The next step is to let others Mac also use the same certificates and provisioning profiles.

Integrate Match to our Fastlane iOS Project

In lesson 3, we use get_certificates() and get_provisioning_profile() to use the valid certificates and provisioning profile to build/archive the app. After used Match, we will have the update for Fastfile and .env file

// Fastfile
lane :build_app do

    // create the build    
    // get_certificates()        
    // get_provisioning_profile()
    match()   // we write the parameter in the environment file
    build_app()
    
    ...
end

// .env_dev_adhoc
/*
CERT_DEVELOPMENT = false 
CERT_FORCE = false         
CERT_USERNAME = <your_apple_id>   
CERT_TEAM_NAME = <your_team_name
CERT_FILE_NAME = <you_file_name>
CERT_OUTPUT_PATH = fastlane_delivery/dev/adhoc/
SIGH_AD_HOC = true,    
SIGH_APP_IDENTIFIER = <your_app_id>,          
SIGH_USERNAME = <your_apple_id>, 
SIGH_OUTPUT_PATH = fastlane_delivery/dev/adhoc
SIGH_PROVISIONING_PROFILE_NAME = <your_provisioning_proflie_name>
*/
// ADD THE FOLLOWING CODE
MATCH_GIT_BRANCH = <branch_name>
MATCH_APP_IDENTIFIER = <your_app_id>
MATCH_TYPE = adhoc
MATCH_READONLY = true # if false, cannot create the certificates and provisioning profile

MATCH_TYPE - only 4 types, development, adhoc, appstore, enterprise, same as Apple Developer Account Provisioning Profile type

MATCH_GIT_BRANCH - the branch you store the certificates and provisioning profiles

MATCH_APP_IDENTIFIER - is an array, you can enter multiple app ids

I use .env_dev_adhoc as an example, you can update your other environment files based on your setting.

Run bundle exec fastlane ios build_app --env dev_adhoc. You will see the new certificate and provisioning profile appear on the Fastlane log.

Custom lane for Certificates and Provisioning Profile

If you want to download all the certificates and provisioning profile in a Mac when you are working on DevOps or other purpose, you can create the following lane to do that.

// Fastfile
desc "Sync Development Certification and Provisioning Profile"
lane :provisioning_profiles_development do
     match()
end
desc "Sync Adhoc Certification and Provisioning Profile"
lane :provisioning_profiles_adhoc do
     match()
end
desc "Sync App Store Certification and Provisioning Profile"
lane :provisioning_profiles_appstore do
     match()
end

// Matchfile
# For all available options run `fastlane match --help`
# git repo to save certification and provisioning profile
git_url("<your_git_url>")
username("<share_apple_developer_id>")
# development provisioning profile
for_lane :provisioning_profiles_development do
   type("development")
   git_branch("<your_branch_name>")
   app_identifier([
      <your_app_id>]
   )
   
   # update to false if it needs to create the profile
   readonly(true)
end
# adhoc provisioning profile
for_lane :provisioning_profiles_adhoc do
   type("adhoc")
   git_branch("<your_branch_name>")
   app_identifier([
      <your_app_id>]
   )
   
   # update to false if it needs to create the profile
   readonly(true)
end
# appstore provisioning profile
for_lane :provisioning_profiles_appstore do
   type("appstore")
   git_branch("<your_branch_name>")
   app_identifier([
      <your_app_id>]
   )
   
   # update to false if it needs to create the profile
   readonly(true)
end

We write the parameters in the Matchfile because we won’t tigger any build. Another reason is that we can create different type of provisioning profile based on the app id.

Now, run bundle exec fastlane ios provisioning_profiles_adhoc. Check the repo and Apple Developer account again, it will have a new commit in repo and save the new created certificates and provisioning profile. Remember to untick the automatic signing option in your Project.

Now, if a new team members who join you team, you only need to run your 3 lanes.

What’s next?

Next lesson, we will introduce Fastlane Gym to replace build_app action in Fastfile. Also, we will talk a little bit about Fastlane action alias.