iOS Apps CI/CD pipeline with GitHub Actions and Fastlane

What is GitHub Actions ?

GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline.

For more information please check the official document of it.

Lets check, how we can use the GitHub Actions to automate the iOS app build process.

To compile and package the iOS applications you need the macOS system. GitHub provides Linux, Windows, and macOS virtual machines to run your jobs/ workflows using GitHub Actions.

Create Sample iOS project

Lets create the sample iOS project using Xcode by selecting the iOS App template.

Add appropriate Product Name, for this article I have added “GithubActionDemo”

Please select the “Include Tests” option to add the test target in our project.

Xcode project setup

Click on the “Next” and complete the project setup. Once done you should be ready with “GithubActionDemo” project with white screen on the simulator.

Create new repository in your GitHub account and push this newly created project to the GitHub repository.

What is fastlane ?

It is the open source platform that is use to automate the development and release process of the iOS and Android apps. For more details please check official documentation of fastlane.

Setup Fastlane locally

Before moving on to the GitHub Actions, lets setup the Fastlane locally on development machine so that you can test the setup locally.

Fastlane can be installed in multiple ways, but since fastlane is the Ruby gem the preferred way to install is via Bundler. Bundler is the dependency manager for the Ruby projects.

Lets install the bundler and add fastlane as it’s dependency using following steps.

• Install the bundler by running gem install bundler command
• Go to root directory of your project and create “Gemfile” using command touch Gemfile
• Open newly created Gemfile and add fastlane dependency in it.

source "https://rubygems.org"
gem "fastlane"

Run bundle install command. It will check the content of Gemfile and automatically installs the ruby packages in your machine. In this case it will install the “fastlane”

Push the “Gemfile” and “fastfile” to the GitHub repository.

Create Fastfile

In fastlane world, we have to create the Fastfile where we can define the different lanes for different automated tasks. For example we can have lane for running unit test cases, capturing screenshots, submitting beta apps, submitting App store builds etc….

For this article purpose we are going to create the simple lane for running the unit test cases.

• Lets create the “fastlane” folder in your projects root directory and create “fastfile” in it.

mkdir fastlane
cd fastlane
touch Fastfile

• Add the lane in Fastfile to run the unit test cases, as below

lane :tests do
 run_tests(scheme: "GithubActionDemo")
end

• To verify the local setup run the command bundle exec fastlane tests

If everything setup correctly, It should compile your iOS project for simulator and run the unit test cases.

Now we have local setup ready, lets create the GitHub Actions flow to run the unit test cases on the CI environment.

Create GitHub Actions workflow

Workflow is the automated process where you define the process in YML file.

• Create .github/workflows folder in your projects root directory.
• Create file github-actions-demo.yml inside the workflows folder, use below commands to do it.

mkdir .github
cd .github
mkdir workflows
cd workflows
touch github-actions-demo.yml
cd ..
cd ..

• Open the newly created “github-actions-demo.yml” file and copy following content in it.

name: GitHub Actions Demo
on: [push]
jobs:
  Explore-GitHub-Actions:
    runs-on: macos-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v1
      - name: Run unit test case
        uses: maierj/fastlane-action@v2.2.0
        with:
        lane: tests

In this workflow we have define the job with name “Explore-GitHub-Actions”, this will be triggered on very push to repository and run the unit test cases using fastlane.

Lets’s look at the workflow syntax line by line

name: The name of the workflow

on: To automatically trigger the workflow on the mentioned event, In this example [push], It indicates on every push to this repository it will trigger the workflow. We can configure this to be more specific also, for example for every push to “main” branch trigger this flow or when someone creates the PR trigger this workflow etc..

jobs: The workflow is made up of one or more jobs, in this case we have created one job with name “Explore-GitHub-Actions”. You can see this name in Github UI in actions section. (Please see image below)

runs-on: It is the name of the runner (virtual machine) where the job will be executing. Since we need mac OS for iOS build hence we choose “macos-latest”

steps: These are steps executing on the virtual Mac machine. We have configured two step in this section as below

1. Checkout repository: It will checkout the code on the mac runner using the v1 version of the checkout action (actions/checkout@v1). This action is provided by the GitHub by default. There are other actions that you can use as per your requirement, please feel free to check the documentation.
2. Run unit test case: It will install the fastlane on the runner and executes the lane “”tests”. It will use the version 2.2.0 of the fastlane-action provided by third party provider (maierj/fastlane-action@v2.2.0). There are several actions available on GitHub marker place. Please feel free to check it https://github.com/marketplace?type=actions.

Push the “github-actions-demo.yml” to the GitHub repository.

If everything configured correctly, it should trigger the new action and run the unit test cases on it.

You can check this in the “actions” section of your repository.

This is the basic tutorial to explain the various building blocks of the GitHub Actions and Fastlane. You can configure various workflows depending on your requirement using it.

Feel free to check the GitHub Actions / Fastlane documentation for more details.

Please add your comment if you have any questions/ suggestion.