GitLab CI/CD runners

You now know how to write a .gitlab-ci.yml file with stages, jobs and scripts. But who actually runs these jobs? The runners, agents that pick up your jobs and run the commands. This guide explains how they work and how to optimize them.

What you will learn

By the end of this module, you will be able to:

• Understand the role of a runner: the agent that runs your jobs
• Tell shared, group and project runners apart: choose the right type for your needs
• Use tags: target a specific runner for a job
• Choose an executor: Docker, Shell or Kubernetes depending on your context
• Diagnose a "pending" job: identify why a job does not start
• Optimize performance: reduce execution times

Prerequisites

Before continuing, make sure you are comfortable with:

• GitLab CI/CD core concepts
• Writing a .gitlab-ci.yml file

What is a runner?

A runner is an agent that:

1. Fetches pending jobs from GitLab
2. Runs the job's commands
3. Sends the results back (logs, artifacts, status)

Source · SVG

Esc to close, + and − to zoom, scroll to move around. 100 % − Fit + Close

What types of runners exist?

Type	Scope	Use case
Shared runners	All GitLab.com projects	Standard projects, no setup
Group runners	Projects of a group	Teams with common needs
Project runners	A single project	Security, performance, specific needs

Swipe to see more

Shared runners

GitLab.com provides shared runners, free of charge (with quotas). They are:

• Preconfigured with Docker
• Available immediately
• Limited in minutes per month (depending on your plan)

To use them, there is nothing to configure: your jobs run on them automatically.

In Settings > CI/CD > Runners, you see the runners available to your project: their status (online/offline), their tags, and whether they are shared or dedicated.

Group runners

Group runners are shared among all the projects of a GitLab group. They are a good compromise between shared runners (too generic) and project runners (too isolated).

Use cases:

• Teams with several projects sharing the same needs (common tech stack)
• Centralized governance: a group admin manages the runners for all projects
• Control of tags and access at the team level

To create a group runner: Group > Settings > CI/CD > Runners > New group runner. The group's projects use it automatically (unless disabled at the project level).

Project runners (self-hosted)

Install your own runner for:

• Performance: dedicated machine, no queue
• Security: jobs that access internal resources
• Specialization: GPU, ARM, specific tools
• Cost: avoid minute quotas

How do you follow job execution?

When a pipeline runs, you can follow its progress in Build > Pipelines:

Each row represents a pipeline with its status, its branch and its trigger. Click a pipeline to see the detail of the stages and jobs:

This graph shows the stages (columns) and the jobs (boxes). The jobs of a same stage run in parallel. Click a job to see its logs in real time:

The logs show each command executed and its output. You see the CI variables (such as $CI_COMMIT_BRANCH) resolved with their actual values.

Executors

The executor defines how the runner runs the jobs:

Executor	Description	Use case
Docker	Each job in an isolated container	Standard, isolation, reproducibility
Docker+Machine	Creates VMs on demand (autoscaling)	Variable load, cloud
Shell	Runs directly on the machine	Hardware access, simplicity
Kubernetes	Ephemeral Kubernetes pods	Existing K8s cluster
SSH	Connects to a remote machine	Deployment to existing servers

Swipe to see more

Recommendation

For most cases, use the Docker executor. It offers isolation and reproducibility without complexity.

Docker executor

The most common. Each job runs in a Docker container.

job:
  image: node:24-alpine@sha256:a0b9bf06e4e6193cf7a0f58816cc935ff8c2a908f81e6f1a95432d679c54fbfd    # Docker image used
  script:
    - npm install
    - npm test

Advantages:

• Complete isolation between jobs
• Reproducible environment
• Wide choice of available images

Drawbacks:

• Image pull time
• No direct hardware access

Shell executor

Runs the commands directly on the runner's machine.

job:
  tags:
    - shell    # Targets a runner with the shell executor
  script:
    - ./build.sh

Advantages:

• Direct hardware access (GPU, USB...)
• No Docker overhead
• Preinstalled tools available

Drawbacks:

• No isolation between jobs
• Dependencies must be installed on the machine

How do tags work?

Tags let you target a specific runner. A job with tags only runs on a runner that has all of those tags.

build:
  tags:
    - docker
    - linux
  script:
    - make build

build-arm:
  tags:
    - docker
    - arm64
  script:
    - make build

On the runner side, tags are defined at registration:

gitlab-runner register \
  --tag-list "docker,linux,amd64"

Mandatory tags

If your runner is configured with "Run untagged jobs: No", it will only run jobs with matching tags.

How do you install a runner?

Linux

1. Download the binary and check its checksum

   Pin the version rather than downloading latest, which changes without notice. The runner version should match your GitLab version (here 19.5.1, the version this course is measured on). GitLab publishes a release.sha256 file next to each version, and sha256sum -c compares the download with it:

   RUNNER_VERSION="19.5.1"   # align with your GitLab version
   base="https://gitlab-runner-downloads.s3.amazonaws.com/v${RUNNER_VERSION}"
   
   curl -fsSLO "${base}/binaries/gitlab-runner-linux-amd64"
   curl -fsSL "${base}/release.sha256" \
     | grep 'binaries/gitlab-runner-linux-amd64$' \
     | sed 's#binaries/##' \
     | sha256sum -c -

   The check must print gitlab-runner-linux-amd64: OK. Any other output means the file is corrupted or altered: delete it and start again. Then install it, with sudo because /usr/local/bin belongs to root:

   sudo install -m 0755 gitlab-runner-linux-amd64 /usr/local/bin/gitlab-runner
   gitlab-runner --version

2. Create a dedicated user

   sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

3. Install and start the service

   sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
   sudo gitlab-runner start

4. Create the runner in GitLab

   In Settings > CI/CD > Runners, click New project runner. Set the tags and options, then GitLab generates a runner authentication token (prefix glrt-).

5. Register the runner

   Use the glrt-... token with the --token option:

   sudo gitlab-runner register \
     --url "https://gitlab.com/" \
     --token "glrt-XXXXXXXXXXXXXXXX" \
     --name "my-docker-runner" \
     --executor "docker" \
     --docker-image "alpine:3.24.1@sha256:28bd5fe8b56d1bd048e5babf5b10710ebe0bae67db86916198a6eec434943f8b" \
     --tag-list "docker,linux"

   --docker-image is the default image of jobs that do not declare their own image:. As in a .gitlab-ci.yml, it is pinned by its digest (@sha256:...), so every job starts from the exact same content.

New registration workflow

Since GitLab 16.0, the recommended workflow uses runner authentication tokens (glrt-...) created through the UI. The old method with --registration-token is deprecated and may be disabled on some instances. Official documentation.

Docker

Align the runner version with your GitLab version (e.g. GitLab 19.5 → Runner 19.5). The image is pinned by its digest, so the tag cannot silently point to other content:

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:v19.5.1@sha256:8e049fb719162488893a9eccc48f3a05259d02f2386dfbb20f3e379a50575afd"

Then register with the glrt-... token:

docker exec -it gitlab-runner gitlab-runner register \
  --url "https://gitlab.com/" \
  --token "glrt-XXXXXXXXXXXXXXXX"

Security: mounting docker.sock

Mounting /var/run/docker.sock gives root access to the host. Any container can create other privileged containers. Safer alternatives:

• Kubernetes executor: isolated ephemeral pods
• Docker-in-Docker (dind) with limited --privileged
• Restrict through allowed_images, allowed_services in config.toml

Kubernetes

Use the official Helm chart. The runnerToken must be a runner authentication token (glrt-...) created through the GitLab UI:

helm repo add gitlab https://charts.gitlab.io
helm install gitlab-runner gitlab/gitlab-runner \
  --set gitlabUrl=https://gitlab.com \
  --set runnerToken="glrt-XXXXXXXXXXXXXXXX" \
  --set rbac.create=true

For production, use a Kubernetes Secret rather than passing the token in clear text:

kubectl create secret generic gitlab-runner-secret \
  --from-literal=runner-token="glrt-XXXXXXXXXXXXXXXX"

helm install gitlab-runner gitlab/gitlab-runner \
  --set gitlabUrl=https://gitlab.com \
  --set runners.secret=gitlab-runner-secret \
  --set rbac.create=true

How do you configure the runner?

The configuration file is /etc/gitlab-runner/config.toml:

concurrent = 4        # Max simultaneous jobs on this runner
check_interval = 3    # GitLab polling interval (in seconds)

[[runners]]
  name = "my-runner"
  url = "https://gitlab.com/"
  token = "glrt-xxxx"
  executor = "docker"

  [runners.docker]
    image = "alpine:3.24.1@sha256:28bd5fe8b56d1bd048e5babf5b10710ebe0bae67db86916198a6eec434943f8b"
    privileged = false
    volumes = ["/cache"]
    pull_policy = ["always", "if-not-present"]  # Fallback if the registry is unavailable

Important parameters:

Parameter	Description
concurrent	Number of simultaneous jobs on this runner
check_interval	Interval between polls to GitLab (spread across the runners in the file)
pull_policy	Pull strategy: always, if-not-present, never (or a list for fallback)
privileged	Privileged mode (required for Docker-in-Docker, security risk)
volumes	Volumes mounted in the containers

Swipe to see more

pull_policy and security

if-not-present improves performance but carries a risk on shared/public runners: a user could access a private image already in the cache. For multi-tenant runners, prefer always. Security documentation.

How do you diagnose a pending job?

Is your job stuck on "pending"? Here are the possible causes:

Symptom	Likely cause	Solution
"Waiting for a runner"	No runner available	Check that the runners are active
"This job is stuck"	Tags do not match	Check the tags of the job and of the runner
Pending for a long time	All runners busy	Increase concurrent or add runners
Pending then fail	Runner offline	Check the gitlab-runner service

Swipe to see more

Diagnosis:

# Check the runner status
gitlab-runner status

# See the registered runners
gitlab-runner list

# Test the connection to GitLab
gitlab-runner verify

In GitLab: Settings > CI/CD > Runners shows the available runners and their status (see the screenshot above).

Why are my jobs slow?

Cause	Impact	Solution
Image pull on every job	+30s to +2min	pull_policy: if-not-present
npm install on every job	+1 to 5min	Use the cache
Overloaded shared runners	Queue	Dedicated runner
Heavy image	Download time	Lighter or custom image

Swipe to see more

Quick optimization

The GitLab CI cache is the most effective lever. An npm install goes from 2 minutes to 10 seconds with a properly configured cache.

pull_policy: if-not-present is relevant on a private, controlled runner. For a shared or public runner, prefer always (risks tied to private images in the cache).

What are the best practices?

1. Use meaningful tags: docker-linux, gpu, prod-deploy
2. Limit production runners: dedicated tags, restricted access
3. Configure concurrent correctly: according to the machine's resources
4. Use pull_policy: if-not-present on a private runner: avoids unnecessary pulls (keep always on shared runners, see the caution above)
5. Monitor your runners: dashboards, alerts if offline

Hands-on lab

The lab "The right image for each job" replays this guide on a GitLab CE forge of your own, set up on a virtual machine with its runner and its registry, rather than on the shared runners of gitlab.com: no minute quota, no identity verification, and a project you can break as often as you need.

Three jobs share the same heavy Python image, and the one that builds the image runs docker build from it, which cannot work. You pick an image that matches what each job does, and give the build job a Docker daemon (building an image is detailed in GitLab registries). Grading is taken on the job logs, never on the file.

The lab starts with dsoxlab run gl-03-images-et-runners, after dsoxlab provision prepares the virtual machine, its runner and its registry. Installing DSOXLab and its prerequisites are described in the DSOXLab documentation.

Guided lab Practice

Learn how to do it

The right image for each job

$ dsoxlab run gl-03-images-et-runners

Environment: VM·Duration: ~30 min

How it is checked: the state of the system is checked after a reboot, not the command you typed.

First time? What DSOXLab is and how to install it

DSOXLab is the command line that prepares a disposable environment (an isolated shell or a VM), runs the lab scenario, then checks the real state of the system and computes a score. Nothing is installed or broken on your workstation.

It needs Python 3.11 or later, uv or pipx, and git. The installation guide details these prerequisites; on Windows, or on a Mac without Python, use the appliance instead.

This lab starts virtual machines: it also needs ansible-playbook, a hypervisor (KVM or Incus), Terraform and hardware virtualization (/dev/kvm), which inside a VirtualBox VM means nested virtualization. The first time, dsoxlab start gl-03-images-et-runners checks all of it before creating the machines. Prepare your machine for vm labs.

Install the CLI and add the catalogue, once:

uv tool install dsoxlab   # or: pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/gitlab-ci-dsoxlab-training

Before you run the lab, check:

• DSOXLab installed
• catalogue available
• compatible environment (isolated shell or VM)

To check, nothing is probed from this page: run dsoxlab doctor. Read the diagnosis

Run this lab, then validate your work:

dsoxlab run gl-03-images-et-runners
dsoxlab check gl-03-images-et-runners

See every lab: dsoxlab list-labs. Track your progress: dsoxlab progress. The full dsoxlab guide covers scoring and the pitfalls.

Key takeaways

1. Runner = agent that runs the jobs on a machine
2. Shared runners are free (with quotas), project runners give full control
3. Docker executor recommended for isolation and reproducibility
4. Tags = target a specific runner (tags: [docker, gpu])
5. Pending job = check tags, active runners, and concurrent
6. Performance = cache, pull_policy, dedicated runners

Knowledge check

Test your knowledge of GitLab CI/CD runners.

Knowledge check

Check what you have learned with this interactive quiz

10 questions

5 min

70% to pass

How it works

• The timer starts when you click Start
• Multiple choice, true/false and short answer questions
• You can move between questions
• Detailed results are shown at the end

Start the quiz

Starts the quiz and the timer

×

See in the glossary →