Registering Runners

Registering a Runner is the process that binds the Runner with a GitLab instance.

Requirements

Before registering a Runner, you need to first:

  • Install it on a server separate than where GitLab is installed on
  • Obtain a token for a shared or specific Runner via GitLab's interface

GNU/Linux

To register a Runner under GNU/Linux:

  1. Run the following command:

    sudo gitlab-runner register
    
  2. Enter your GitLab instance URL:

    Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
    https://gitlab.com
    
  3. Enter the token you obtained to register the Runner:

    Please enter the gitlab-ci token for this runner
    xxx
    
  4. 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
    
  5. 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):
    my-tag,another-tag
    
  6. Enter the Runner executor:

    Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell:
    docker
    
  7. 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):
    alpine:latest
    

macOS

To register a Runner under macOS:

  1. Run the following command:

    gitlab-runner register
    
  2. Enter your GitLab instance URL:

    Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
    https://gitlab.com
    
  3. Enter the token you obtained to register the Runner:

    Please enter the gitlab-ci token for this runner
    xxx
    
  4. 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
    
  5. 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):
    my-tag,another-tag
    
  6. Enter the Runner executor:

    Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell:
    docker
    
  7. 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):
    alpine:latest
    

    Note be sure Docker.app is installed on your mac

Windows

To register a Runner under Windows:

  1. Run the following command:

    ./gitlab-runner.exe register
    
  2. Enter your GitLab instance URL:

    Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
    https://gitlab.com
    
  3. Enter the token you obtained to register the Runner:

    Please enter the gitlab-ci token for this runner
    xxx
    
  4. 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
    
  5. 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):
    my-tag,another-tag
    
  6. Enter the Runner executor:

    Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell:
    docker
    
  7. 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):
    alpine:latest
    

If you'd like to register multiple Runners on the same machine with different configurations repeat the ./gitlab-runner.exe register command.

FreeBSD

To register a Runner under FreeBSD:

  1. Run the following command:

    sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
    
  2. Enter your GitLab instance URL:

    Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
    https://gitlab.com
    
  3. Enter the token you obtained to register the Runner:

    Please enter the gitlab-ci token for this runner
    xxx
    
  4. 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
    
  5. 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):
    my-tag,another-tag
    
  6. Enter the Runner executor:

    Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell:
    docker
    
  7. 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):
    alpine:latest
    

Docker

To register a Runner using a Docker container:

  1. Run the following command which will mount the Runner's config directory under /path/to/config:

    docker run --rm -t -i -v /path/to/config:/etc/gitlab-runner --name gitlab-runner gitlab/gitlab-runner register
    
  2. Enter your GitLab instance URL:

    Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
    https://gitlab.com
    
  3. Enter the token you obtained to register the Runner:

    Please enter the gitlab-ci token for this runner
    xxx
    
  4. 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
    
  5. 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):
    my-tag,another-tag
    
  6. Enter the Runner executor:

    Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell:
    docker
    
  7. 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):
    alpine:latest
    

One-line registration command

If you want to use the non-interactive mode to register a Runner, you can either use the register subcommands or use their equivalent environment variables.

To see a list of all the register subcommands, use:

gitlab-runner register -h

To register a Runner using the most common options, you would do:

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:3 \
  --description "docker-runner" \
  --tag-list "docker,aws" \
  --run-untagged \
  --locked="false" \

If you're running the Runner in a Docker container, the register command would look like:

docker run --rm -t -i -v /path/to/config:/etc/gitlab-runner --name gitlab-runner gitlab/gitlab-runner register \
  --non-interactive \
  --executor "docker" \
  --docker-image alpine:3 \
  --url "https://gitlab.com/" \
  --registration-token "PROJECT_REGISTRATION_TOKEN" \
  --description "docker-runner" \
  --tag-list "docker,aws" \
  --run-untagged \
  --locked="false"