Computer Science

Set up GitLab CI with an iOS project that uses Cocoapods

We all write tests for our applications and keep them in version controlled systems like GitLab or GitHub. However, how can we configure GitLab to run Unit and UI tests for us?

I couldn’t find a lot of documentation explaining how to set up continuous integration for iOS on GitLab, therefore I am writing this article.

Victor Peschenkov explains in his article how to use GitLab CI with Fastlane. My article focuses on how to run everything yourself.


In order to set up GitLab Runner for iOS we need the following tools:

Please install these tools now before continuing.

Configure Xcode

Make sure to download Xcode form the Mac App Store. Once it is installed open it and create a project to make sure it is completely installed and running.

iOS Project

I created a sample project to get you started more quickly.  Feel free to fork it or use your own project. Please verify your installation using:

  • git checkout
  • switch into the project folder and run pod install
  • run the following command on your machine to verify that you can build and run the tests successfully – which means no “failures” or other error messages
xcodebuild test \
-workspace "CI Sample.xcworkspace" \
-scheme "CI Sample" -destination 'platform=iOS Simulator,name=iPhone XR,OS=12.0' \
| xcpretty -s

Installing GitLab Runner

iOS projects require a special GitLab Runner. Usually gitlab-runner can be hosted on any machine (virtual machine, Linux-, Mac- or Windows-system). However, iOS related projects need a GitLab Runner, that is hosted on a Mac with Xcode in order to build successfully.

Install GitLab Runner on a Mac

Follow these steps to configure GitLab Runner on your Mac:

  • use the command brew install gitlab-runner
  • go to your GitLab instance to Settings > CI/CD
  • disable shared runners (alternatively you can use tags to only use your Mac for building the iOS project)
  • go toSpecific Runners and save your GitLab server url and token
GitLab CI/CD Settings page showing URL and token for specific runner
(token has been removed on purpose)
  • register a your runner as described in GitLabs documentation
  • gitlab-runner register

          1. when prompted, enter the url form above
          2. next up, enter the registration token
          3. name your runner
          4. leave the tags blank
          5. use the shell executor

  • start your runner using:
cd ~
gitlab-runner install
gitlab-runner start

Please note, should you restart your computer you’ll likely have to start the GitLab Runner again.

Reload the CI/CD settings page. If everything worked out, you should be able to see your runner in the Specific Runners section:

Listing of successfully activated specific GitLab runners

Create gitlab-ci.yaml

Once we have a GitLab runner for iOS and a project, we need to configure it. Please add a gitlab-ci.yaml and insert:

  - build

  LC_ALL: "en_US.UTF-8" # apparently xcpretty won't function correctly otherwise

  - gem install cocoapods
  - pod install

  stage: build
    - xcodebuild clean -workspace "CI Sample.xcworkspace" -scheme "CI Sample" | xcpretty
    - xcodebuild test -workspace "CI Sample.xcworkspace" -scheme "CI Sample" -destination 'platform=iOS Simulator,name=iPhone XR,OS=12.0' | xcpretty -s

As soon as you commit this file, GitLab-CI should kick in and start building your project and then run the tests.

That’s it you’ve done it!


What do you think? Please let me know if you run into any problems or have improvement suggestions.



Also published on Medium.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.