Install GitLab Runner on macOS

Install GitLab Runner on macOS

This is a post in our series about Gitlab, for the earlier post see


A Gitlab Runner allows Gitlab to run Pipelines and Jobs (which can be used for anything e.g. Tests and Builds), if you run your own Gitlab Server, need something not supported by free gitlab runners such as more responsive/time or a Windows, OSX or ARM32/ARM64 environment.

If you want to do any kind of iOS/macOS testing and/or building with gitlab pipelines you’ll need to setup a macOS gitlab-runner. This blog post hopes to walk you through that process.

In the future Gitlab hopes to make this a brew package which will make this a lot simpler, but for now you have to manually download the macOS binary.


  • Download the binary for your system:
    sudo curl --output /usr/local/bin/gitlab-runner
  • Give it permissions to execute:
    sudo chmod +x /usr/local/bin/gitlab-runner
  • Register the runner
    gitlab-runner register
  • Enter your GitLab instance URL:
    Please enter the gitlab-ci coordinator URL (e.g. )
  • Enter the token you obtained to register the Runner:
    Please enter the gitlab-ci token for this runner
  • Enter a description for the Runner, you can change this later in GitLab’s UI:
    Please enter the gitlab-ci description for this runner
    [hostame] my-runner
  • Enter the tags associated with the Runner, you can change this later in GitLab’s UI:
    Please enter the gitlab-ci tags for this runner (comma separated):
  • Choose whether the Runner should pick up jobs that do not have tags, you can change this later in GitLab’s UI (defaults to false):
    Whether to run untagged jobs [true/false]:
    [false]: true
  • Choose whether to lock the Runner to the current project, you can change this later in GitLab’s UI. Useful when the Runner is specific (defaults to true):
    Whether to lock Runner to current project [true/false]:
    [true]: true
  • Enter the Runner executor:
    Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell:
  • If you chose Docker as your executor, you’ll be asked for the default image to be used for projects that do not define one in .gitlab-ci.yml:
    Please enter the Docker image (eg. ruby:2.1):
  • Install the Runner as service and start it:
    cd ~
    gitlab-runner install
    gitlab-runner start
  • The runner is installed and will be run after a system reboot.

Update Procedure

  • Stop the service:
    gitlab-runner stop
  • Download the binary to replace the Runner’s executable:
    curl -o /usr/local/bin/gitlab-runner
  • Give it permissions to execute:
    chmod +x /usr/local/bin/gitlab-runner
  • Start the service:
    gitlab-runner start

Gitlab has very detailed FAQ section, where if you’re having an issue it’s more than likely it’ll be found there