Install and configure local gitlab runner on OSX

The process of installing gitlab runner on the osx is pretty straightforward and well documented on official Gitlab documentation , however what I find lacking, is the configuration part where you define your actual runners.

So this is a small write up about the whole process which hopefully save me and you some time in the future


The installation is pretty straightforward and can be performed by brew

brew install gitlab-runner

Runner registration

Launch registration with gitlab-runner register

Runtime platform                                    arch=amd64 os=darwin pid=75951 revision=f0a95a76 version=14.5.0
Enter the GitLab instance URL (for example,
Enter the registration token:
Enter a description for the runner:
[MC02CF7V4MD6R]: macbook-alekc
Enter tags for the runner (comma-separated):
Registering runner... succeeded                     runner=xxx
Enter an executor: docker, parallels, ssh, docker+machine, docker-ssh+machine, custom, docker-ssh, shell, virtualbox, kubernetes:
Enter the default Docker image (for example, ruby:2.6):
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!


You can register gitlab runner to start automatically by running

brew services start gitlab-runner

Fine Tuning

You can amend the configuration by editing following file: ~/.gitlab-runner/config.toml, it should look like this:

 1concurrent = 1
 2check_interval = 0
 5  session_timeout = 1800
 8  name = "macbook-alekc"
 9  url = ""
10  token = "***"
11  executor = "docker"
12  [runners.custom_build_dir]
13  [runners.cache]
14    [runners.cache.s3]
15    [runners.cache.gcs]
16    []
17  [runners.docker]
18    tls_verify = false
19    image = "alpine"
20    privileged = false
21    disable_entrypoint_overwrite = false
22    oom_kill_disable = false
23    disable_cache = false
24    volumes = ["/cache"]
25    shm_size = 0

You would probably want to change following settings:

  • concurrent: the amount of concurrent builds. I find the default number (1) to be very restrictive, and put usually something like 3-5
  • runners.docker.privileged: if you are using DIND (docker in docker), you will need to set this flag to true. Keep in mind that it’s a potential security escalation vehicle, so unless you need this, it’s probably better keep it at default value.
  • runners.docker.volumes if you are doing any builds in your pipeline, you might want to add /var/run/docker.sock:/var/run/docker.sock to your shared volumes