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

8 min readJan 23, 2023

Introduction

I recently developed and published my first app to the App Store and during my development time I wanted to implement the best practices in my development and distribution process. When it came to distribution phase of my app, I had to learn a number of essential details related to App Store distribution, and realized that automating my builds, tests, and deployment processes would save me a good amount of time in the future updates.
I researched different options for automating the distribution pipeline, such as Xcode Cloud, GitHub Actions, Bitrise, Travis CI, and more, and found that Fastlane is an effective tool to start with, as it works well with most existing CI/CD tools (except Xcode Cloud). I decided to implement my continuous delivery (CD) pipeline with Fastlane and was able to do so by creating a solid and efficient pipeline that streamlined my app’s certifications/provisioning profile, build, test, build number increment and Testflight upload processes.
In this tutorial, I will share my experience and guide you through the steps of setting up Fastlane and using it for making a pipeline on an example app.

Note: If you want to check out the app here is the link: App Store Link

I broke the article down into 3 parts to make it more readable and manageable for the audience because a lengthy article can be overwhelming to read.

What will you learn and understand in part 1:

Nature of Fastlane 🌏
Setup Fastlane in your iOS Project. 💻

GitHub link

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

Lets Get Started.

Let’s start from the table of contents.

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

Part 1 Table of contents:

Prerequisites and resource links
What is Fastlane? How it works?
Step 1. Install Fastlane and add Fastlane to Project

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.

Prerequisites and links

Before diving into Fastlane, it’s important to have a few things in mind. Firstly, it’s assumed that you already have a basic understanding of how to submit an iOS app to the Apple App Store. If you’re new to this process, it may be challenging to fully grasp every step in this tutorial. To gain a better understanding, it’s recommended that you read up on the basics of submitting an iOS app to the App Store before continuing with Fastlane.
Secondly, in order to distribute your app to Testflight, you must be enrolled in the Apple Developer Program and have access to App Store Connect. Finally, for reference, a finish sample project can be found in the provided repository link.
GitHub link: GitHub link
Useful resource: How to enroll to Apple Developer Program? YouTube link
Useful resource: How to submit iOS app to the App Store? YouTube link

What is Fastlane? How it works?

What is Fastlane?

Fastlane is a tool that helps iOS developers automate the process of deploying their apps. It allows for the automated uploading of apps to Testflight, either through a trigger or manual command in the terminal.
Fastlane streamlines the process of building, testing, and releasing iOS apps by providing a set of tools (called “actions”) to automate each step of the deployment process. The screenshot below shows how to easily upload an app to Testflight with just one line of code in the terminal.😎

Screenshot 1: This is how I can simply upload my app to the Testflight with one line in terminal.

How it works?

Fastlane is a collection of tools, known as “actions,” that helps automate different tasks in the iOS app development process. These tasks include setting up provisioning profiles, registering the app on App Store Connect, running tests, submitting the app to the App Store, uploading to Testflight and more. You can access a list of all the available actions on the official Fastlane website: Fastlane Actions.

Screenshot 2: Screenshot of a Fastlane website with fastlane actions

Each step that is configured in the deployment pipeline is called a “lane.” To understand Fastlane, it’s important to know that a “lane” is a specific set of tasks that can be executed together in a specific order. For example, you can create a lane called “upload_my_app_to_testflight” and define it by inserting all the necessary actions in the correct sequence. We will discuss how to configure lanes and pipelines in more detail later in the part 2 and part 3. You can also find more information on how Fastlane works on the official website: Fastlane website: Fastlane website.

Screenshot 3: Screenshot of a Fastlane website with How Fastlane works

Step 1. Install Fastlane and add Fastlane to Project

Fastlane install

There are several options available to install fastlane, however, I used Homebrew to install fastlane on my macbook. If you don’t have Homebrew you can install homebrew with this link: Homebrew.
If you do not want to use homebrew, you can check other installation options here: website. To install Fastlane with brew, open Terminal and type the following code:

brew install fastlane

Add Fastlane to Project

Now, let’s add Fastlane to our project. The example app that we’ll be using is called “SomeApp,” it’s a basic single view app that allows you to change the color of a container. However, it’s important to note that the functionality of the app is not important for this tutorial, as we will not be making any changes to the project code.

Currently, our project folder is empty and does not have Fastlane installed. Let’s add it now.

Screenshot 5: Project folder without fastlane.

To add Fastlane to, open your terminal and navigate to your project directory. Then run the command “fastlane init.” This command initializes Fastlane in your project.

fastlane init

This is how what you need to have in terminal

After pressing enter, the command line needs to show you this prompt:

Fastlane offers a few default templates for your project. These include:

Automating the process of taking screenshots for the App Store.
Automating the distribution of beta versions of the app to TestFlight.
Automating the distribution of the app to the App Store.
Manual setup.

For this tutorial, we will be using the manual setup option, which allows us to configure everything ourselves. To choose this option, type “4” in the terminal and press Enter.

After running the “fastlane init” command, you should now have a new “fastlane” folder and a file called “Gemfile” in your project directory. These are the two items that were added to your project as part of the Fastlane setup process.

What is Gemfile?

The “Gemfile” is a file used by the Ruby programming language to manage dependencies for a project when using Fastlane. However, for the sake of simplicity, we will not discuss it yet, and will instead focus on the main aspects of working with Fastlane.

Fastlane folder

Open fastlane folder and you will see two files: Appfile and Fastfile.

What is Appfile? The Appfile is a file that stores constant app related details like the app’s name, bundle identifier, and the Apple ID used to log in to App Store Connect. However, in this tutorial we will mainly work with .env environment files instead. One thing that is important to set in the Appfile is the app_identifier variable, which is the app’s bundle identifier. To do this, open the Appfile and add the following code, replacing ‘your-app-bundle-identifier’ with the actual bundle identifier of your app.

app_identifier "your-app-bundle-identifier"

What is Fastfile? The “Fastfile” is the key file when working with Fastlane, we will be using it frequently. It has access to the constant variable names defined in the Appfile. This file is where you define the lanes of your Fastlane deployment pipeline, which are groups of actions that can be executed together. For instance, a common lane could be named “deploy” that runs actions such as building the app, taking screenshots and uploading the app to the App Store.

Fastlane folder with Appfile and Fastfile files.

Open the “Fastfile” in any text editor of your choice. Some developers prefer using Visual Studio as it provides a user-friendly interface for editing the Fastfile. If you open the Fastfile, you will see a basic setup with some boilerplate code that may seem unfamiliar at first. But don’t worry, I will guide you through each step you need to take.

First, let’s remove the commented lines above “default_platform(:ios)” line. And now let’s go over this file.

Let’s break down the code below into pieces.

default_platform(:ios)

platform :ios do
  desc "Description of what the lane does"
  lane :custom_lane do
    # add actions here: https://docs.fastlane.tools/actions
  end
end

This code is written in Ruby and is using the Fastlane tool. It sets the default platform to iOS and creates a custom lane specifically for the iOS platform. The desc method is used to provide a brief description of what the lane does, which is useful for documentation. Inside the lane :custom_lane do block, actions are defined that will be executed when this lane is called, while custom_lane is just the name of the lane. These actions can be found in the Fastlane documentation. Overall, this code is setting up a specific lane for the iOS platform to run certain actions.

Now we can create an app on the App Store and then start defining out pipeline.

Follow up

Congratulations!✅
You’ve completed the introduction and setup phases of the tutorial. It’s time to move on to the most exciting part — creating a deployment pipeline! Head over to Part 2 to continue.

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