How to set up GitLab CI for iOS in three relatively simple steps

Hint: It is not hard at all.

My own GitLab set-up for work as well as this post came to life thanks to Angelo Stavrow’s post from 2016. Make it all spicier adding fastlane to the jam, find the link for my next article at the end of this post.

Introduction

As developers, young or old, junior or senior, or whatever the title, we all hear about CI/CD and the tools available — there are a lot of paid ones while others are free if your project is open source for example. Cool, I know. But about work that is not open source? You are in luck if you are using GitLab because it comes with CI built-in for free, no matter the project. That sounds like… a goood plan :-).

I will not go into explaining what CI/CD is, you can easily google it. But I need to note that the greater advantage, for myself at least, of having CI is that it will make you write those damn tests you have been procrastinating. So, lets do this.

What set-up is used for this post?

• A Mac mini running macOS Sierra 10.12.6
• Xcode 8.3.3 with the iOS 10.3 SDK

First step — setting up your Xcode project

• Start of by creating your project including Unit and/or UI tests and linking it with a corresponding GitLab repository.
• Really, really make sure that you share your project’s scheme because otherwise GitLab CI cannot locate the context it needs to build and test your project. To do that, you need to open your project in Xcode and choose Product > Scheme > Manage Schemes from the tab menu.
• When the menu window shows up, tick the Shared box corresponding to your project’s scheme and then click the Close button

There is no need to share any dependency schemes.

• When done with the above steps, you can commit and push.

A good idea is to get xcpretty. It transforms the output of your build into something way more readable.

Second step — installing and registering a GitLab Runner

To really get a good sense of what Runners are, you can check out GitLab’s documentation about them. Explained in short — it is a service on your computer (it could be a remote server somewhere but it will be on your Mac since you are an iOS developer which makes you special :-)) that runs a certain build and its corresponding test process which you get to set up in a special configuration file.

The actual installation of a GitLab runner on your Mac is quite straightforward so I do recommend following the instructions provided by our GitLab friends specifically for macOS.

It is the registration of your GitLab Runner that can be confusing at certain steps. There are indeed instructions on how to do that too(so please follow them) but I do need to point out a few particularities:

• When performing the registration process, make sure it is done in user-mode, meaning — there is no need for using sudo in front of every command. Actually, make sure you do not use sudo here because the registration will not work. Believe me, I tried it.
• In step 2 in the instructions, you are asked to enter your GitLab instance URL. What worked for me was entering https://gitlab.com/ci
• In step 8 in the instructions, you are asked to enter the Runner executor. Enter shell.
• Your runner should be up and running. You can see that from the command line using the command gitlab-runner verify or when you go to your project’s page in GitLab’s web site, choose Settings > CI/CD.

• There are two things to note in the above screenshot — the first one is that I have set up two Specific Runners for my project and I am using just one of them, and the second one is that I have disabled the Shared Runners which is how I make certain that a Specific Runner I have chosen runs my project. The Shared Runners will not work for an iOS project.

Third step — configuring the build and test settings using a YAML file

For those of you who have experience with other CI tools may have seen or configured a YAML file before. Well, with GitLab CI, the configuration is pretty similar — it is just that the YAML file needs to named .gitlab-ci.yml.

For the others that have no experience with such configurations, please check out the instructions on creating a .gitlab-ci.yml file and you will see how easy it is. Just make sure that the file is saved in the proper place in your Xcode project folder.

I will provide you with two examples of a .gitlab-ci.yml file created for iOS projects:

• The first one is Angelo Stavrow’s. Scroll down to Installing and registering the GitLab Runner. A bit bellow it you will see a configuration with respective explanation for a Xcode project with no dependencies(Cocoapods for example). The configuration looks like this:

stages:
  - build

build_project:
  stage: build
  script:
    - xcodebuild clean -project ProjectName.xcodeproj -scheme SchemeName | xcpretty
    - xcodebuild test -project ProjectName.xcodeproj -scheme SchemeName -destination 'platform=iOS Simulator,name=iPhone 6s,OS=9.2' | xcpretty -s
  tags:
    - ios_9-2
    - xcode_7-2
    - osx_10-11

• The second one is a set-up of mine for a project with Cocoapods. I only have one stage but I am building for two different environments, and I have no tags because my runner is set up to work without them. Please do notice the difference in the naming after the xcodebuild script command. I am clean building and testing a workspace instead of a project for just one branch named addingTestsToProject:

stages:
  - build
  
build_project_1:
  stage: build
  script:
    - xcodebuild clean -workspace WorkSpaceName.xcworkspace -scheme SchemeName | xcpretty
    - xcodebuild test -workspace WorkSpaceName.xcworkspace -scheme SchemeName -destination 'platform=iOS Simulator,name=iPhone SE,OS=10.3.1' | xcpretty -s
  only:
    - addingTestsToProject
    
build_project_2:
  stage: build
  script:
    - xcodebuild clean -workspace WorkSpaceName.xcworkspace -scheme SchemeName | xcpretty
    - xcodebuild test -workspace WorkSpaceName.xcworkspace -scheme SchemeName -destination 'platform=iOS Simulator,name=iPhone 6,OS=10.3.1' | xcpretty -s
  only:
    - addingTestsToProject

Conclusion

This is how it is done! Well, most of it at least because, believe me, a YAML file can be really sophisticated. What I provided you with is quite simple and I hope it will be a good start for some and refreshment for others.

In my next post, I will share how I got to set up GitLab CI and fastlane to work together to save me time and effort in developer activities. Read about that here.

Until then, please do ask a question if you find something unclear and do share advice on what I could do better.