Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 36 ยท Runners and Jobs

Installing and Registering a GitLab Runner

Install GitLab Runner on Linux or in Docker, create a runner in the UI, register it with an authentication token, and understand every setting in config.toml.

To run pipelines on your own machine you need two things: the GitLab Runner program installed there, and a registration that links it to your GitLab instance, project or group. The product cannot run on this website, so this lesson describes the real commands precisely and uses a small stand-in to teach the configuration file. Where we are unsure about an exact current menu label, we say so; the official documentation always has the latest wording.

Step 1: install the program

On Linux, the runner is available as a package from GitLab's package repository, as a standalone binary, and as a container image. A typical Debian or Ubuntu installation is: add GitLab's repository (its instructions give a one-line script), then

Terminal
sudo apt-get install gitlab-runner

A standalone binary install works on any Linux, macOS or Windows machine:

Terminal
sudo curl -L --output /usr/local/bin/gitlab-runner \
  "https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64"
sudo chmod +x /usr/local/bin/gitlab-runner
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start

Or run it as a container, keeping the configuration in a volume:

Terminal
docker run -d --name gitlab-runner --restart always \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:latest

Mounting the Docker socket gives the container control over the host's Docker, which is powerful: only do this on a machine you trust. Check gitlab-runner --version and gitlab-runner status afterward.

Step 2: create the runner in GitLab

Current GitLab versions use an authentication token workflow, where you create the runner in the web interface first:

  1. Decide the scope: project (Settings, CI/CD, Runners), group (the group's Build or Settings area, Runners), or instance (Admin area).
  2. Choose New project runner (or group / instance runner).
  3. Pick the operating system, enter tags (for example docker, linux) and whether to run untagged jobs, and optionally lock it to the current project, set a maximum timeout and a description.
  4. Click Create runner. GitLab shows a command containing a token that starts with glrt-. Copy it: it is displayed once.

Older tutorials describe a registration token shown on the settings page and passed to gitlab-runner register. That method is deprecated in favor of runner authentication tokens, so prefer the flow above if your instance offers it.

Step 3: register

On the runner machine run:

Terminal
sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "glrt-REPLACE_WITH_YOUR_TOKEN" \
  --executor "docker" \
  --docker-image "alpine:latest" \
  --description "build-server-1"

Without --non-interactive it asks questions instead: the GitLab URL, the token, a description, and the executor (and a default image for Docker). Tags and "run untagged" were set in the web form during creation, so the command does not ask for them. After registration the runner appears in the list with a green online dot within a minute (if not, see the troubleshooting list below). Commit a pipeline whose job uses one of its tags and watch it get picked up.

The config.toml file

Registration writes the runner's configuration to /etc/gitlab-runner/config.toml (when run as root; ~/.gitlab-runner/config.toml otherwise). It is a TOML file with global settings on top and one [[runners]] block per registered runner:

TOML
concurrent = 4
check_interval = 3

[[runners]]
  name = "build-server-1"
  url = "https://gitlab.com"
  token = "glrt-REDACTED"
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = false
    pull_policy = ["if-not-present"]
    volumes = ["/cache"]

The important settings:

Setting Meaning
concurrent Maximum jobs this runner process executes at once, across all its [[runners]]
check_interval Seconds between polls for new jobs
limit (per runner) Cap on jobs for that one registration
executor How jobs execute: shell, docker, kubernetes, ...
[runners.docker] image Default image when a job does not specify one
privileged Gives containers extra power; needed for Docker-in-Docker but risky
pull_policy always, if-not-present or never for images
volumes Directories mounted into job containers

Edit the file, and the runner reloads it automatically (no restart needed for most changes). Keep it readable only by root, because it contains the token.

The stand-in below parses a config.toml with Python's standard TOML reader and reports the capacity and each runner's executor. It also checks a couple of common mistakes. It is a model of how to reason about the file, not the Runner's own validation.

Python Stand-in: read a runner's config.toml

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

tomllib ships with Python 3.11 and later, so it also runs in the browser Python. Notice how the nested table [runners.docker] becomes the key docker inside the preceding [[runners]] item: TOML attaches a sub-table to the last array element. Try print(runner) to see the structure.

Running several runners, and capacity

You can register the same machine several times, for example one docker runner and one shell runner. The global concurrent caps the total jobs the process runs. To use a bigger machine fully, raise concurrent (and per-runner limit if set) in proportion to CPU and memory, and watch for jobs slowing each other down.

Python Stand-in: how long does a queue take to drain?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Managing runners from the command line

Terminal
sudo gitlab-runner list              # runners in config.toml
sudo gitlab-runner verify            # check tokens still work
sudo gitlab-runner restart
sudo gitlab-runner unregister --name build-server-1
sudo gitlab-runner run               # run in the foreground, showing logs

Running gitlab-runner run (or reading the service logs with journalctl -u gitlab-runner) is the fastest way to see why a runner is offline.

Troubleshooting registration

  • Runner shows offline: the service is stopped, or it cannot reach the GitLab URL (proxy, DNS, firewall, TLS certificates). Check gitlab-runner verify.
  • Job pending although runner online: tags mismatch or untagged jobs disabled (runners overview).
  • Docker not found: the docker executor needs Docker installed and the runner user in the docker group.
  • Certificate errors on a self-signed instance: provide the CA with --tls-ca-file or configure it in config.toml.
  • Token invalid: the runner was deleted in the UI; register a new one.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In the current workflow, where does the glrt- token come from?

    You create the runner in GitLab, which shows a runner authentication token (glrt-...) once; you pass it to gitlab-runner register.
  2. 2. What does concurrent in config.toml control?

    concurrent is the global limit on simultaneously running jobs for that runner process.
  3. 3. Why is privileged = true risky?

    Privileged containers have broad access to the host; use them only when required, such as Docker-in-Docker, and on trusted code.
  4. 4. Which command shows why a runner may be offline by running it in the foreground?

    gitlab-runner run keeps the process in the foreground with visible logs.

Summary

  • Install GitLab Runner from a package, a binary or a container.
  • Create the runner in the web interface to get a glrt- token, then run gitlab-runner register.
  • Settings live in config.toml: concurrent, check_interval, executor and executor-specific tables.
  • Use gitlab-runner verify, list and run to inspect problems.
  • Keep tokens private and avoid privileged containers unless needed.

Next: Executors and Job Environments