Home iOS Continuous Integration and Delivery using Bitrise and Fastlane

iOS Continuous Integration and Delivery using Bitrise and Fastlane

In this tutorial, we will go through all the steps to automate our tests, beta releases and even the app store releases, but before we start I need to thank Moski Doski for helping and guiding me through this journey.

What we will achieve at the end?

At the end of this series, after pushing your code to the develop branch, all unit tests will run and after that, it will send a success or failure message to slack. In case of merging your code to the master branch, Bitrise will make a build for you, upload it to iTunes connect, and then publish it to your testers.

Let’s start!

In this part we will understand four main things before we start, What is continuous integration, continuous Delivery, Fastlane and Bitrise.

1-Continuous integration: In continuous integration, the developers merge their changes back to the main branch as often as possible. The developer’s changes are validated by creating a build and running automated tests. By doing this, you avoid the integration hell that usually happens when people wait for release day to merge their changes into the release branch.

2-Continuous delivery: Continuous delivery is an extension of continuous integration to make sure that you can release new changes to your customers quickly in a sustainable way. This means that on top of having automated the testing, you also have automated your release process and you can deploy your application at any point of time by pushing your code to a specific branch.

3-Bitrise: Bitrise is a Continuous Integration and Delivery (CI/CD) Platform as a Service (PaaS) (you will ask your self what is PaaS, don’t worry as we will talk about this in a moment), so Bitrise is a collection of tools and services to help you with the development and automation of your software projects.

Now what is a Platform as a Service (PaaS), PaaS is a category of cloud computing services that provides a platform allowing customers to develop, run, and manage applications without the complexity of building and maintaining the infrastructure.

4-Fastlane: Fastlane is an open-source platform aimed at simplifying Android and iOS deployment. Fastlane lets you automate every aspect of your development and release workflow. like generating screenshots, dealing with provisioning profiles, and releasing your application.

The App

let’s have a look at the app that we will use through this series, it’s a very simple app, the app has one label and two buttons the first button sums the number 9 and 10, and the second button subtract one from this number.

We have three main classes, ViewController, MyMath and MyAppTests, the MyMath class is just a small helper to help us do the calculations, while the MyAppTest class has tests for MyMath class.

You can get the starter project from here


The first step we need to install Fastlane you can install Fastlane by running the following command:

sudo gem install fastlane

next, go to the project directory and run the following command to add Fastlane to our project:

fastlane init

It will show to you a list of choices, choose “Manual setup” as we will manually set up our project to automate our tasks, press enter and wait until it finishes.
Now if we go to our project we will find a new folder, Fastlane folder, open it and you will find the Fastlane file, open this file with any editor of your choice.

In this file we will write our lanes if you are asking what is a lane, it’s a group of actions to automate a task like pushing a new build to TestFlight.

First, let’s add a description for our lane, you can add whatever you want for the description, I’ll write what we will do in this lane, “Push new build to the TestFlight”, We will name the lane to beta as it will push a beta build to TestFlight.

Now let’s run the lane that we just created, Go to the terminal and write:

fastlane beta

It will show us a success message but it didn’t do anything as we didn’t write any actions, don’t worry as that’s what we are going to do now!


The first action we will use is the Match action, Match creates all required certificates & provisioning profiles and stores them in a separate git repository. Every team member with access to the repo can use those credentials for code signing. Match also automatically repairs broken and expired credentials. It’s the easiest way to share signing credentials across teams.

Run the following command line on your project to initialize Match:

fastlane match init

The terminal will ask you where you want to store your certificates, select git

Next, it will ask you for the git URL, make a private git repo on Github or Bitbucket and use the URL of that repo.

This will create a Matchfile inside your Fastlane folder. The Matchfile will contain the git repo URL and the type of storage.

Now we will add the match action to our lane and pass the type parameter as appstore as we will build the app for iTunes connect.

match(type: 'appstore')

Next, run the fastlane beta command again, it will ask you about the username enter your username.

Important: You must add the username in your Matchfile, you can find the Matchfile inside the fastlane folder.

Then it will ask you to enter the app identifier, to not be asked about this value, you can specify it using ‘app_identifier’ parameter in the match action.

match(type: 'appstore', app_identifier: "your_app_identifier")

This is the final look of our beta lane:

Now run the beta lane again, it will ask you about a passphrase for the git repo, this passphrase will be used to encrypt/decrypt your certificates, make sure to remember the passphrase, as you’ll need it when you run Match on a different machine.

Note: If you don’t have an app created on iTunes connect with the same app_identifier then you will get the: Couldn’t find bundle identifier ‘your_app_identifier’ for the user ‘you_username’ so you need to go to the iTunes connect and create new app.

Now all the required keys, certificates and provisioning profiles are installed for your app. And if you open the git link you will find the files there.

Increment the build and version numbers and add badge

Next thing we will do, we will increment the build number and the version number and keep them inside a variable as we will show the version number and the build number on the app icon, the increment version number take a “bump_type” parameter. There are three different values for the bump type: patch, minor and major.

For us, we will increment the patch number, as the beta will be small changes and bug fixes.

version_number = increment_version_number(bump_type: "patch")
build_number = increment_build_number

This is the final look of our beta lane after adding the increment build number and increment version number actions.

Run the Fastlane beta again, you will get an error, this error because Apple Generic Versioning is not enabled in this project, to fix this issue:

1-Open your project.
2-Select your app target.
3-Select build settings.
4-Search for “Apple Generic”.
5-Change the version system to “Apple Generic”.

6- Search for “Current Project Version” and set it to 1

7-Go to info tab and change the “Bundle versions string, short” to 1.0.0, and the “Bundle version” to 1.

Run the “fastlane beta” command again you will get a new error, open your project -> your app target -> build settings, then search for “SRCROOT”, remove “$(SRCROOT)/” and run the beta lane again.

Run again, now everything works fine If you check your project, you will find that the version and build numbers changed.

Now it’s the time to add the badge to the icon, go back to the Fastlane file and add the add badge action.

add_badge(shield: "")

Now “add_badge” action takes deferent parameters, the parameter that we will use is the shield parameter, this parameter adds a shield to your app icon from shields.io, open the website and scroll down to the “Your Badge” section you will find three boxes, the first box is the label, the second is the message and the third is the color, fill the three boxes as in the image below:

Press “Make Badge” you will get the following image:

This what we will get when apply the add badge action to our icon. Now, in the same way, we will set the shield parameter with

“the_version_number - the_build_number - the_color”

I’ll use the previous build and version number variables and for the color, I’ll use red.

add_badge(shield: "#{version_number}-#{build_number}-red")

Now if you try to run the command you will get an error, because you need to install the “fastlane-plugin-badge” plugin, to install the plugin open the Gemfile in your main directory.

and add this line:

gem 'fastlane-plugin-badge'

Run the command again and you will find that the icons changed!


gym action builds and packages iOS apps for you. It takes care of all the heavy lifting and makes it super easy to generate a signed ipa.

Now in our Fastlane file add the gym action after the add_badge action.


The final look after adding gym action to our file:

Run the fastlane beta command line again and wait until it finishes building.

Now go to your project folder you will find that you have an ipa generated for you!

Now, How to upload the build to TestFlight?


We will upload the build using another action called Pilot, Pilot is an action from Fastlane to manage your TestFlight testers and builds from your terminal.

Open the Fastfile again and after the gym action add:

pilot(username: "your_user_name")

The final look after adding pilot action to our file:

Now go back to your app and in the Info.plist add a new key


with boolean value NO.

To know more about this value please visit session 302 from WWDC.

Run the fastlane beta again, and wait until it finishes.

If you go to iTunes connect you will find that there is a new build uploaded to your tester!.


Next thing we will do, whenever the build uploaded successfully or if something went wrong, we will send a message to slack. For that, we will use another action called slack.

After pilot action add the following action:

slack(message: "App successfully released!")

You can change the message with whatever you want. Now if you try to run the beta lane, it will ask you about the WebHook for your slack group, if you don’t want to be asked about this again you can add the slack_url parameter with the URL to your group.

To get the WebHook URL from slack:

1- Go to apps “https://yourgroup.slack.com/apps”.

2- Search for “Incoming WebHooks”.

3- Click on “Add Configuration”.

4- It will ask you to select a channel to post to, select any channel you want.

5- Click on add.

6- Now copy the “Webhook URL” and add it to the slack_url parameter.

The final look after adding slack action to our file:

Run the beta lane again, and wait until it finishes. You will see that you got a success message from Fastlane!

Tests Lane

In this lane we will run the unit tests inside our app, it’s a simple lane that contains two actions, the scan action, and slack action.

The scan actions is an action from Fastlane to run the app unit tests.


The final look of our tests lane:

After we reached to this point we have done most of the work, and actually using just this locally will save us a lot of time for you!. but with Bitrise we will save even more time and make things even better!.


If you remember in the first part I said that when we pushe the code to the develop branch we will run the tests lane, and when we pushe the code to the master branch we will run the beta lane to upload the build to iTunes connect.

Steps to add git:

1-If you don’t have a git repo, go to Github and make a new repository.

2-navigate to your project directory and initialize git

git init

3-Add all the files in the directory to git

git add .

4-Add new remote to git

git remote add origin https://github.com/your_username/repo_name.git

5-Commit the files

git commit -m "first commit"

6-Push the code to master

git push origin master


Go to Bitrise website and register or log in if you already have an account.

After login, in the right section click on add new app

Now we will go through seven steps to set up our Bitrise app and connect it with our git repository.

1-Select the privacy of the app, if you select private just you and organization members can see it, but if you select public anyone can see your logs and configs.

2-Now you need to choose a repository, click on the repo you want to add Bitrise to.

3-Setup repository access, if you are the admin on that repository you can easily give access to Bitrise just by clicking on No, auto-add SSH key.

4-Choose branch, write master as for now we have just one branch.

It will start validating the branch. it will take less than a minute.

if you got an error saying No shared schemes found make sure that you have a shared schema. for more information click here

5-Now from the project build configuration select Fastlane.

then confirm.

6-In this step you can add app icon that you will see on Bitrise.

7-Web hooks, the Web hooks will allow the git to call Bitrise when there is a new push to the git repository. Click on register a web hook for me.

After clicking on the button, Bitrise will run a new build for you. it will fail don’t worry, this error because we need to connect the developer account to Bitrise.

1-Click on the icon on the top right then click on account settings.

2-In the left section select Apple developer account.

3-Click on connect button.

4-Enter the user name and password then click on store credentials.

5-Now go back to the project page and select the team tab.

6-Scroll down to the Connected Apple Developer Portal Account section, and select the account you just added.

now go back to the project select workflow

then secrets

press on add new, we will add two secrets, MATCH_PASSWORD and FASTLANE_PASSWORD.

MATCH_PASSWORD: Put your passphrase that we used while we were configuring Match action.

FASTLANE_PASSWORD: Put your iTunes connect account password here.

Now go again to the project page and click on Start/Schedule Build button.

Then click on the Start build button.

Wait until it finishes successfully!.

if the build failed with the following error:

Click on workflow

from the Workflows tab, select the Do anything with Script step, below the # write your script here comment, add the following three lines:

gem uninstall bundler --force
gem install bundler -v 2.0.1 --force
gem install fastlane -NV

if you got another error saying:

Error cloning certificates git repo, please make sure you have access to the repository - see instructions above

Then you need to add SSH key to your account level in Github/Bitbucket. Please visit this link for more information.


A workflow is a collection of steps, environment variables, and other configurations for a single run. we will run each workflow when changes happen on the git, like push code to the master branch.

To add workflow:

1-Open the project then select Workflow.

2-Click on + Workflow button

3-Enter the name of the workflow

Now you have a new workflow, to change the lane that this workflow runs, scroll down and select fastlane then change fastlane lane.

To run the tests lane, follow the same steps, but this time name the workflow as tests and in Fastlane set the Fastlane lane to tests.


To add a new trigger:

1- In the same page select Triggers.

2-Click on Add Trigger button

3-Now in the push branch enter the name of the branch that you want the build to start when you push the code to.

4-Press on the save button.

If you want to add a trigger to run the tests workflow, click again on add trigger, set the name of the push branch as develop, and in the workflow select tests workflow.

Now from the terminal make some changes and push the code to git, and check the Bitrise builds page!!.

The end

Congratulations!!, now the beta lane will execute each time you push the code to the master branch and it will upload a new build to iTunes connect. And if you pushed the code to the develop branch the tests will run and in case of success, it will send a message to slack!.

There is still a lot of things to learn and tools to try!, if you need to know more about Bitrise and Fastlane, you can visit Fastlane documentation and Bitrise documentation.

If you have any questions you can send me a message on Twitter or facebook. Also you can check my Github page or my Apps.

This post is licensed under CC BY 4.0 by the author.