GitLab CI -Setting up GitLab Runner on Mac

Published in

Mac O’Clock

4 min readMay 27, 2020

Setting up CI infrastructure is something, what almost every mobile developer has to do. This time I validate GitLab CI. In this article I will walk you through the process of setting up a Gitlab Runner on our Mac.

I had the following initial setup:

self-hosted GitLab
MacMini ( macOS Catalina 10.15.4), where the builds are supposed to run

The official documentation is a good starting point, but nevertheless I was rather puzzled sometimes. I will tell you also about the difficulties I had, so you can spare some time ;)

Step 1 — Create a Project on a GitLab

Create an Xcode Project and Push it to GitLab. You need Maintainer or Owner permission to access the project settings in GitLab. Actually for this tutorial you even not necessarily need Xcode project, but we want to work further on it, don't we?

Step 2 — Install Gitlab Runner

It is possible to install the runner manually or with Homebrew (you can read all the details here). I’ve chosen the manual way .

At first download the binary

curl --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-darwin-amd64

Then give it permission to execute

chmod +x /usr/local/bin/gitlab-runner

Step 3— Register Gitlab Runner

Now you have to register the runner so that it can communicate with the Gitlab instance. You have to perform the register command and provide the needed input. URL and Token you can found in the settings of your project as shown below.

gitlab-runner registerPlease enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/):
// your gitlab urlPlease enter the gitlab-ci token for this runner:
// token from your projectPlease enter the gitlab-ci tags for this runner (comma separated):
// you may configure tags later, for the first try we can just leave it emptyPlease enter the executor: kubernetes, docker-ssh, parallels, shell, virtualbox, docker-ssh+machine, custom, docker, ssh, docker+machine:
// for iOS we need shell

Here you can get all the needed info for registering the runner

And now…. it is failing 💔 Anyway it was the case by me. The error message was this:

couldn't execute POST against https://your_gitlab/api/v4/runners: Post https://your_gitlab/api/v4/runners: x509: certificate signed by unknown authority
PANIC: Failed to register this runner. Perhaps you are having network problems

But stop panicking!

What did help to me was: export site certificate as .pem file (you can do directly from the browser) and attach it to registration command:

gitlab-runner register — tls-ca-file path/to/your/certificate.pem`

The remaining steps are the same. After you successfully performed you will see the runner in your GitLab project, you can explort and make more configuration.

Step 4 — Create .yml File

To tell the runner what it should do, you need to create a .yml in our project. So create a file named `.gitlab-ci.yml` in the root folder of your project (where the xcproject file is). There are lots of configuration and structuring possibilities for pipeline, but for now we will keep very-very simple. The main configuration element of pipeline is job. I add just one job with a simple “Hello CI” command… ok and perform tests, but this one is optional ;)

test_job:
    script:
      - echo "Hello CI!"
      - xcodebuild test -workspace YourProject.xcodeproj -scheme YourScheme -destination 'platform=iOS Simulator,name=iPhone 11'

There is a listing tool in GitLab in CI/CD section in the menu. You can just check if our script is correct.

After you commited the file, the job will automatically start. Congratulations! You have configured your first GitLabCI pipeline! 😎

Step 5— Troubleshooting

Or it may happen, you see, what I have initially seen — an error.

And the Logs seem to be not very helpful

It turned out, the reason was rvm. Of course you can get rid of it completely, but probably you still need it. I have found the solution here:

remove rvm initialization from your .bash_profile file
add this line source "$HOME/.rvm/scripts/rvm" to your .gitlab-ci.yml

Probably it is not yet the perfect one, but it helps.

👆 It may be very helpful to run the gitlab runner in debug mode from the terminal on your machine. The output contains more information as logs in the web-ui. Just open your project and call this command:
gitlab-runner --debug exec shell test_job

So now we managed to set up the Gitlab runner. Next step is further pipeline configuration with fastlane scripts. Yo can find it here.