Effortlessly Implement CD in your iOS Project: A Complete Guide to Setting up Fastlane [Part 2/3] (2023)

12 min readJan 23, 2023

Welcome to part 2 of our Fastlane tutorial for iOS. In the first part of this tutorial, we provided some useful resource links for getting started with Fastlane and learnt the essential information about the Fastlane. We also covered an introduction to what Fastlane is, how it works, and the steps for installing Fastlane and adding it to your project.

In this second part of the tutorial, we will dive deeper into the capabilities of Fastlane and show you how to use it to automate various tasks in your iOS development workflow. We will cover topics such as how to register the app on the App Store Connect and handle provisioning profiles with Fastlane.

What will you learn and understand in part 2:

How to create an app in the App Store Connect 📱
How to automate provisioning profiles and certificates in Fastlane 📄

GitHub link

If you want to check the final project, you can access it here: https://github.com/mukatayev1/SomeApp-Fastlane-Tutorial

Lets Continue.

Let’s start from the table of contents.

The following is the table of contents Part 2 and Part 3:

Part 2 Table of contents:

Step 2. Create an app in App Store Connect
Step 3. Fastfile Lane 1: Fastlane Match and provisioning profiles/certificates

Part 3 Table of contents:

Step 4. Fastfile Lane 2: Running tests
Step 5. Fastfile Lane 3: Project build
Step 6. Fastfile Lane 5: Testflight upload
Step 7. Full pipeline test
Useful tips and tricks
Conclusion and follow up.

Where did we stop?

In the last part of the Part 1, we simply broke down the initial Fastfile’s boilerplate code. The next step for us is to create an app in the App Store Connect portal.

Step 2. Create app in App Store Connect

Fastlane has an action called “produce” that can be used to create an app on the App Store Connect. But this method requires developer’s credentials and only needs to be done once. So, I recommend manually creating the app on the App Store Connect portal instead of using this Fastlane action. This way, you don’t have to worry about managing developer credentials and you don’t need to create the app every time you run your pipeline.

Let’s start creating the App in the App Store Connect

Firstly, Go to the Xcode project and copy the Bundle Identifier. (See image below)

Open the Identifiers in Apple Developer link. And press ‘+’ button. (See image below)

Choose App ID and click continue. (See image below)

Select App and continue. (See image below)

Paste the bundle identifier, add your description, and click continue. And finish the registration by clicking “Register”. Now you have a new identifier with which you can register a new app. (See image below)

Paste Bundle Identifier and register the identifier

Now Open the App Store Connect and login. (See image below)

Click plus and select a New App. (See image below)

Enter the required info about the app and click “Create”. (See image below)

Congrats you just created your app in the App Store Connect! The next step for us is to setup Provisioning profiles with Fastlane.

Step 3. Fastfile Lane 1: Fastlane Match and provisioning profiles/certificates

This step was referenced a lot from the tutorial article ‘How to setup Fastlane and Match to release iOS apps automatically on CI/CD server’ by Douglas Iacovelli on Medium:
Reference link: link
Thank you Douglas!

When working on an iOS project in Xcode, you may have come across the “Automatically manage signing” checkbox in the Signing & Capabilities section. This feature allows Xcode to handle the creation and maintenance of provisioning profiles, App IDs, and certificates for you.

However, when working with Fastlane, you no longer have Xcode to handle this process for you. This is where the match action comes in. It allows you to manage your provisioning profiles and certificates, and ensures that everyone on your team is using the correct ones. This ensures that the signing and distribution process is streamlined and consistent, and also helps to keep your provisioning profiles and certificates secure. So let’s get started.

Let’s setup match

The purpose of the first lane is to setup provisioning profiles and certificates that are needed to sign and distribute an iOS app in the App Store Portal. The fastlane provides us with a great action called “Match” that does a lot of work for us! I will show you how to set it up! Here is the documentation link: Match in Fastlane.

According to the official documentation, this is what it states:

🔄 Automatically sync your iOS and macOS keys and profiles across all your team members using git
📦 Handle all the heavy lifting of creating and storing your certificates and profiles

First of all, Match needs to have an access to Git repo, Google Cloud or Amazon S3 to be able to store and access the code signing identities. We will continue with Git as it is convenient choice for us.

First of all, Match it needs access to a Git repository, Google Cloud, or Amazon S3 to store and access code signing identities. In this tutorial, we will use a Git repository as it is the most convenient option. To set up Match, you need to:

Create an empty GitHub repository
Initialize Match
Create an environment file (.env files) with the necessary information and add it to your .gitignore
Run Match and verify the setup.

Create an empty GitHub repository

To set up Match, you need to create a new private repository on GitHub. If you have an organization, it would be a good idea to create the repository within your organization. However, using a personal GitHub account is also an option. To create the repository, go to GitHub and follow the steps to create a new repository, make sure to set it as private.

After creating the repo please copy the SSH (not HTTPS) link and save it for later use. If you do not have SSH Authentication with GitHub on your Mac machine here is the a nice tutorial how to setup one: Git SSH Authentication. Also remember that you will not need to do anything manually like creating folderes or inserting something with the created repo! So just create the repo and copy its url.

After creating the repository, please copy the SSH (not HTTPS) link and save it for later use. If you do not have SSH Authentication set up with GitHub on your Mac machine, refer to this tutorial on how to set it up: Git SSH Authentication” Additionally, note that you will not need to manually create any folders or add any files to the newly created repository. Simply create the repository and copy its URL.

Initialize Match

Now navigate to project directory and run the following code in command line to initialize match and paste github private repo’s url and add

fastlane match init

When you run the command to initialize Match, you may be prompted to select a storage mode. In our case, we will be using the Git storage mode. To select this option, simply type ‘1’ in the prompt.

Choose any of the match storage modes. In our case it’s git.

After typing that, you will need to paste the github url that we created earlier like in the image below.

After pasting the GitHub URL and pressing Enter/Return, you should receive a message indicating that the Matchfile was successfully created. The message should read “Successfully created ‘./fastlane/Matchfile’. You can open the file using a code editor.” This confirms that the Matchfile has been created and is ready for editing. (See the image below)

Also if you check the fastlane folder, now you need to have new file called Matchfile. We don’t need to open and type anything there, since we already all necessary information

Create an environment file (.env files) with the necessary information and add it to your .gitignore

To setup the environment files, open the Gemfile in your project directory

Add the following code to the file

gem "dotenv"

And run the following code in command line:

bundle install

After successfully installign the gem, let’s create two environment files:

First file: .env.default.sample file that is just a sample file with no information that is going to be used. It’s just a template sample.
Second file: .env.default file is an important file with all important information. Remember that this file needs to be put in .gitignore because you don’t want this file to be pushed to your project repo.

Now, change directory to your fastlane folder in the project directory and run the following two commands to create to files:

cd fastlane 
touch .env.default.sample
touch .env.default

If you want to see hidden folders, just press “Shift+Command+.” This is how your fastlane folder needs to look like.

Paste the following content to your .env.default.sample file:

# These keys must be filled in order to fetch the certificates

# Git basic authorization for match encoded in base64
# This is only needed if the user is not authenticated using ssh on git or if you're running on CI/CD server.
# MATCH_GIT_BASIC_AUTHORIZATION=

# Your local Mac machine Password is used to encrypt/decrypt certificates
# MATCH_PASSWORD=

# (Optional) Your local machine password, such as the one you use to login.
# MATCH_KEYCHAIN_PASSWORD=

# Fastlane Team ID
# FASTLANE_TEAM_ID=

# Not needed unless you are generating the certificates
# Team's shared apple id, which should be the only creator of the certificates.
# WARNING: By any chance you should use your own account.
# MATCH_USERNAME=

# CI only keys for uploading app to store
# APP_STORE_CONNECT_API_KEY_KEY_ID=
# APP_STORE_CONNECT_API_KEY_ISSUER_ID=
# APP_STORE_CONNECT_API_KEY_KEY=

Let’s briefly go through the values. These values are used for local development.

MATCH_GIT_BASIC_AUTHORIZATION — allows each developer on the team to use their own account. If you are authenticated with SSH on git, you do not need to fill this in.
MATCH_PASSWORD — is used to encrypt and decrypt certificates, so it is important not to lose it. This is just a password for you mac machine.
FASTLANE_TEAM_ID — is a team id that is being used in Apple Developer.
MATCH_USERNAME — This is an email account that is being used in Apple Developer Portal to release and manage your app.
APP_STORE_CONNECT_API — values that have this prefix are the values that you will need to make the fastlane automatically communicate with App Store servers for your app release. Make sure that your App Store Connect Key has access level “App Manager. What is App Store Connect API and how to set it up, please visit the following useful links:
Youtube: How to grant API key access to Apple App Store Connect?
Apple documentation: Creating API Keys for App Store Connect API

Once you finish setting up the App Store Connect API Key, let’s continue with filling .env.default. Now you need to have three values App Store Connect API related key id, issuer id and file with .p8 extension (example name: AuthKey_R932K1MCKG.p8) that you downloaded.

Open the .env.default file and copy the code from the .env.default.sample file, then add the necessary values to the variables and uncomment the content.

The contents of your .env.default file should resemble the following, with all information filled in with appropriate values

This is how my .env.default file looks like.

Don’t forget to add the .end.default file to .gitignore file!
If you don’t have .gitignore file, create one. Change directory to project directory an type:

touch .gitignore

Open the file and paste the following content if you want to ignore other fiels that are usually ignored.

## User settings
xcuserdata/

## Obj-C/Swift specific
*.hmap

## App packaging
*.ipa
*.dSYM.zip
*.dSYM

## Playgrounds
timeline.xctimeline
playground.xcworkspace


.build/

# fastlane

fastlane/report.xml
fastlane/Preview.html
fastlane/screenshots/**/*.png
fastlane/test_output
fastlane/.env.default

iOSInjectionProject/

### SwiftPackageManager ###
Packages
xcuserdata

Otherwise, you can just add this line:

fastlane/.env.default

And you might need to refresh file index for .gitignore file to make the updated .gitignore work. Read more this stackoverflow to solve it: link.

Run Match and verify the setup.

Congrats on making this far 😎

Now you need to run two fastlane commands in the terminal to setup the provisioning profiles and ceritificates:

fastlane match development

Type your bundle identifier if the following prompt shows up asking you app identifier:

Asking bundle identifier prompt

After setting up the development certificates, run the match action for appstore, and if you use adhoc releases too run the match for adhoc too!

fastlane match appstore

If you have successfully installed the certificates, you need to have the following message:

If there is any issues, you might need to revoke the certificates with match nuke action and create the certificates again. Read more on the official documentation, Nuke section: link

Congratulations, all difficulties are behind and you have left only one small thing to do!

Wrap up: Let’s complete the final two tasks

Add the “match” action to our Fastfile as the first lane that will be executed every time the pipeline starts.

Open Fastfile and add the following line to create a property for app_identifier that accesses Appfile and gets value of app identifier.

app_identifier = CredentialsManager::AppfileConfig.try_fetch_value(:app_identifier)

Then let’s define a lane called match_certificates. Add the following code to your Fastfile

  desc "match certificates"
  lane :match_certificates do
    match(type: "development", 
    app_identifier: app_identifier
    )
    match(type: "appstore",
    app_identifier: app_identifier
    )
  end

Here, we create a lane called ‘match_certificates’. Within this lane, we execute the ‘match’ action twice, once for the ‘development’ environment and again for the ‘appstore’ environment.

This is how my Fastfile looks like so far.

If you want to test this lane, you can just open terminal with your project directory and type the following:

fastlane match_certificates

The success message should say: “fastlane.tools finished successfully 🎉”

One last adjustment in Xcode.

Open the Xcode and navigate to Signing & Capabilities.

Uncheck the “Automatically manage signing” and select ‘match Development’ certificate that was generated by match action.

Great work! You have successfully completed half of the Fastlane pipeline setup.

In this tutorial, we created an app in the App Store Connect portal and set up the first lane to automatically configure our provisioning profiles. In the final part of this tutorial, we will define the remaining lanes to deploy our app to Testflight.

Follow up

If you would like to continue, let’s proceed to the final step of uploading it to TestFlight in Part 3.

If you have any further questions or would like to share your thoughts on the topic, please leave a comment below. Thanks for your support and you can contact me everywhere:

LinkedIn: https://www.linkedin.com/in/aidosmukatayev/

GitHub: https://github.com/mukatayev1