Setting up GitLab CI for iOS projects

Mar 10, 2016

In this post I'll show you how to set up GitLab CI for your iOS projects, step-by-step, from start to finish.

Why CI?

Continuous integration (CI) is great tool for helping developers be more productive and write higher- quality code. By automatically running a suite of tests every time a commit is pushed, everyone can see the results of changes to the codebase, and take action to make integration faster and easier.

GitLab comes with CI built-in for all projects, for free.

It's beyond the scope of this tutorial to go into details on best practices, workflows, and advantages/disadvantages of CI. In short, however, here's what happens when you enable it for your Xcode project:

  1. You make changes to your copy of the codebase and push a commit to GitLab.
  2. GitLab recognizes that the codebase has changed.
  3. GitLab triggers a build with the GitLab Runner you set up on your Mac for the project.
  4. The GitLab Runner runs through the build and test process you specified in .gitlab-ci.yml.
  5. The GitLab Runner reports its results back to GitLab.
  6. GitLab shows you the results of the build.

This post builds on Jeremy White's blog post, going into a little more detail and correcting some steps for the environment described in the next section.

Assumptions and environment

This post will provide a step-by-step guide to setting up GitLab CI for your iOS projects, from start to finish. First, however, we need to make a few assumptions.

GitLab's strategy document hinges on one key idea: everyone can contribute. As such, this post is written for readers of nearly all levels of experience. However, given that CI is a relatively advanced topic, we're going to assume some basic knowledge of how to create Xcode and GitLab projects, as well as some familiarity with Terminal and git.

This post was written with the following development environment in mind:

We'll also assume you've already created a new GitLab project. If you haven't, go ahead and do that now.

Setting up your Xcode project

We'll start by creating a new single-view iOS project in Xcode.

Creating a new Xcode project.

Give your project a name and make certain that the Include Unit Tests and Include UI Tests options are enabled for the project. Xcode will create a template test class with some sample tests, which we'll use in this post as the test suite that GitLab CI runs to verify a build. Choose a name for your project and click on Next.

Enable unit and UI tests in your project

Choose where you'll save your iOS project. If you like, let Xcode create the git repository on your Mac.

Let Xcode initialize your git repository.

Once Xcode has created and opened your iOS project, you need to share its scheme. Apple's documentation defines schemes nicely:

A scheme is a collection of settings that specify which targets to build, what build configuration to use, and the executable environment to use when the product specified by the target is launched.

By sharing your scheme, GitLab CI gets context it needs to build and test your project.

To share a scheme in Xcode, choose Product > Scheme > Manage Schemes.

Share your scheme.

Click on the Close button.

Your Xcode project has been created with two test files; one includes sample unit tests, and the other includes sample UI tests. You can run Product > Test to run these tests, which will build your project, launch the Simulator, install the project on the Simulator device, and run the test suite. You can see the results right in Xcode:

Test suite success in Xcode.

The green checkmarks next to the test functions (both in the file, and in the Test navigator) show that all tests passed. We won't be referring to the Xcode project anymore, so if you like, you can close it.

Next, open Terminal and navigate to the folder you created for your iOS project.

It's convenient to add a standard .gitignore file. For a Swift project, enter:

$ curl -o .gitignore

For an Objective-C project, enter:

$ curl -o .gitignore

The curl command conveniently downloads the contents of the page at the given URL into a file named .gitignore.

If Xcode initialized the git repository for you, you'll need to set the origin url to your GitLab project (replaceing <username> with your GitLab username and <project> with the project name:

$ git remote add origin<username>/<project>.git

The final step here is to install xcpretty. When Xcode builds and tests your project, xcpretty will transform the output into something more readable for you.

Installing and registering the GitLab Runner

The GitLab Runner is a service that's installed on your Mac, which runs the build and test process that you set up in a configuration file. You can follow the installation instructions for OS X, but we'll need to make some changes to the register the runner step:

$ gitlab-ci-multi-runner register
WARNING: Running in user-mode.                     
WARNING: The user-mode requires you to manually start builds processing: 
WARNING: $ gitlab-runner run                       
WARNING: Use sudo for system-mode:                 
WARNING: $ sudo gitlab-runner...                   

If you're using self-hosted GitLab, the coordinator URL will be http(s)://url-of-your-gitlab-instance/ci`.

Please enter the gitlab-ci coordinator URL (e.g.

The CI token for your project is available on GitLab's Project Settings page, under Advanced Settings. Each project has a unique token.

Please enter the gitlab-ci token for this runner:
<CI runner token from Project > Settings > Runner>

The register process suggests the name of your Mac as a description for the runner. You can enter something different if you like, or just hit return to continue.

Please enter the gitlab-ci description for this runner:

Enter whatever tags you'd like to further identify this particular runner. It's particularly helpful when you need a particular build environment—for example, iOS 9.2 on Xcode 7.2 on OS X 10.11 could use tags like ios_9-2, xcode_7-2, and osx_10-11. This way, we can filter our build stages in GitLab by toolchain, platform, etc.

Please enter the gitlab-ci tags for this runner (comma separated):
ios_9-2, xcode_7-2, osx_10-11

The GitLab Runner will register the runner and give it a unique runner ID.

Registering runner... succeeded                     runner=s8Bgtktb

The GitLab Runner has to run xcodebuild to build and test the project, so we select shell as the executor:

Please enter the executor: virtualbox, ssh, shell, parallels, docker, docker-ssh:
Runner registered successfully. Feel free to start it, but if it's running 
already the config should be automatically reloaded! 

Continue with the rest of the Runner installation instructions (install and start), per the documentation.

Go to the Runners page in your Project Settings and voilà:

The GitLab Runner is recognized in GitLab's Project Settings.

Your GitLab Runner is recognized and (almost) ready to go!

You can verify this by running

$ gitlab-ci-multi-runner verify
WARNING: Running in user-mode.                     
WARNING: The user-mode requires you to manually start builds processing: 
WARNING: $ gitlab-runner run                       
WARNING: Use sudo for system-mode:                 
WARNING: $ sudo gitlab-runner...                   
Veryfing runner... is alive                         runner=25c780b3

Note that they have the same ID (in this case, 25c780b3).

The last thing to do is to configure the build and test settings. To do so, open your text editor and enter the following:

  - build

  stage: build
    - 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
    - ios_9-2
    - xcode_7-2
    - osx_10-11

Save this file in your Xcode project folder as .gitlab-ci.yml, and don't forget the period at the beginning of the file name!

Update: To clarify, the .gitlab-ci.yml file should go in the folder you created for your iOS project, which is also typically where your Xcode project file (ProjectName.xcodeproj) is found. Thanks to commenter Palo for pointing this out!

Let's go through the file with some detail:

There are also some things to look out for:

There's a simple tool for "linting" (i.e., validating) your .gitlab-ci.yml in GitLab. From your GitLab project page, click on Builds in the sidebar, then in the upper-right corner, click on CI Lint:

Accessing the GitLab CI script linter.

Paste the contents of your .gitlab-ci.yml file into the text box and click on Validate. You should see something like:

Status: syntax is correct

This won't tell you if your project name or the Simulator chosen is correct, so be sure to double-check these settings.

The .gitlab-ci.yml file is extremely customizable. You can limit jobs to run on success or failure, or depending on branches or tags, etc.—read through the documentation to get a feeling for just how flexible and powerful it is.

Setting up your GitLab project for CI

Actually, there's really not much to do here! CI is enabled by default on new projects. If your iOS project has some environment variables you want to keep secret, but you want to keep the project public on GitLab, you may want to disable Public builds in Project Settings, under Continous Integration. This will hide the build results from everyone except members of the project.

You may also want to go to Runners under your Project Settings and click Disable shared runners, as they're not needed anyhow—we're using a project-specific runner.

We're now ready to trigger a CI build!

How to trigger builds

To trigger a build, all you have to do is push a commit to GitLab. From the Terminal:

$ git add .
$ git commit -m "First commit."
[...commit info...]
$ git push origin master
[...push info...]

If everything worked, and you installed the GitLab Runner on the same machine, you'll notice that Simulator launches, installs your iOS app and launches it, and then goes back to the home screen.

Go to the Builds page of your GitLab project and have a look at the results!

The Build page after your first CI build.

Click on the <span style=color:green>✔︎ success</span> button to see the build output:

The build results page.

Here you'll see the output from all the steps you requested in your .gitlab-ci.yml file. At the bottom of the log, you should see something like:

All tests
Test Suite GitLab-CI-for-iOSTests.xctest started
    . testExample (0.001 seconds)
    T testPerformanceExample measured (0.000 seconds)
    . testPerformanceExample (0.324 seconds)

	 Executed 2 tests, with 0 failures (0 unexpected) in 0.325 (0.328) seconds

All tests
Test Suite GitLab-CI-for-iOSUITests.xctest started
    . testExample (3.587 seconds)

	 Executed 1 test, with 0 failures (0 unexpected) in 3.587 (3.589) seconds

Build succeeded.

Now you can go ahead and start writing tests for your code, and every time you push a commit, GitLab will diligently fetch the project, clean it, and then build and test it. If the build fails, you can take action to fix the commit.

Starting and stopping the runner on your Mac

The GitLab Runner includes several convenient commands, which you can list easily:

$ gitlab-ci-multi-runner --help
   gitlab-ci-multi-runner - a GitLab Runner

   gitlab-ci-multi-runner [global options] command [command options] [arguments...]
   1.0.4 (014aa8c)
   Kamil Trzciński <> 
   archive	find and archive files (internal)
   artifacts	upload build artifacts (internal)
   extract	extract files from an archive (internal)
   exec		execute a build locally
   list		List all configured runners
   run		run multi runner service
   register	register a new runner
   install	install service
   uninstall	uninstall service
   start	start service
   stop		stop service
   restart	restart service
   status	get status of a service
   run-single	start single runner
   unregister	unregister specific runner
   verify	verify all registered runners
   help, h	Shows a list of commands or help for one command
   --debug			debug mode [$DEBUG]
   --log-level, -l "info"	Log level (options: debug, info, warn, error, fatal, panic)
   --help, -h			show help
   --version, -v		print the version

You may want to stop the Runner so that a build isn't immediately triggered by a pushed commit:

$ gitlab-ci-multi-runner stop
$ gitlab-ci-multi-runner status
gitlab-runner: Service is not running.

In this case, any builds pushed will show up as pending and will be triggered as soon as you restart the Runner:

$ gitlab-ci-multi-runner start
$ gitlab-ci-multi-runner status
gitlab-runner: Service is running!

Any pending builds in the queue will then be triggered, launching Simulator and running the test suite normally.

Advanced: archiving the project automatically

Let's say that, if we commit to master, we want GitLab CI to not only build and test the project, but also provide some continuous delivery, where it creates an application archive, and uploads it to GitLab.

We start by modifying our .gitlab-ci.yml file to add an archive stage and an archive_project job:

  - build
  - archive

  stage: build
    - 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
    - ios_9-2
    - xcode_7-2
    - osx_10-11

  stage: archive
    - xcodebuild clean archive -archivePath build/ProjectName -scheme SchemeName
    - xcodebuild -exportArchive -exportFormat ipa -archivePath "build/ProjectName.xcarchive" -exportPath "build/ProjectName.ipa" -exportProvisioningProfile "ProvisioningProfileName"
    - master
    - build/ProjectName.ipa
    - ios_9-2
    - xcode_7-2
    - osx_10-11

The archive_project job runs two scripts: the first cleans and archives your Xcode project, and the second builds an .ipa file; the only setting means that this job will only run when we commit to master. Notice that it also defines artifacts; after the ProjectName.ipa application archive is created, this option uploads it to GitLab, where you can later download it from the Build page.

In the archive_project job's exportArchive script, make sure you pass in the correct ProvisioningProfileName. It's possible that the archive_project job will fail if your developer keys are in the login Keychain, because it's not unlocked in the script. The simplest way to fix this without putting your password in a script is to open Keychain Access on your Mac and drag and drop them to the System Keychain.

Now, when we commit to master, the build will also show us the archive results, along with the option to download or browse our build artifacts!

The archive results page.

Other salient points

About guest author Angelo Stavrow

Angelo is a Quality Engineer and Software Developer living in Montreal, Canada. He believes that open, honest, collaboration is the best path towards building great things and great teams.

Live webcast: GitLab CI

Sign up for our webcast on April 14th, which includes an overview and tutorial about using GitLab CI. Meet people from the GitLab team and get your questions answered live!

Can't make it? Register anyway, and we'll send you a link to watch it later!

Install GitLab on your own server in 2 minutes

Browse all posts

For the latest and most detailed news follow @gitlab on Twitter. Future blog posts suggestions.