GitLab CI/CD jobs aren’t run by GitLab itself, but by a separate program, GitLab Runner. GitLab.com provides shared runners, which come with a limited number of compute minutes per month on the free plan, and with a self-managed GitLab you have to set up a runner yourself anyway. With your own runner, the jobs run on your machine: with as many resources as you give it, with access to your internal network, and without per-minute charges. In this article we install GitLab Runner with the Docker executor on a Debian or Ubuntu server, and register it for a project.
What machine should you install it on?
The runner itself doesn’t need a powerful machine, but the jobs (builds, tests, building Docker images) can need a lot more. For a small team, a good starting point is:
- 2–4 vCPUs, 4–8 GB of memory, 50–100 GB of SSD (Docker images and the cache take up space quickly),
- Debian 12/13 or Ubuntu 24.04/26.04 LTS,
- a separate virtual machine, not the production application server, and not an LXC container either: Docker works predictably in a virtual machine. We wrote about the difference between LXC- and KVM-based virtualisation on the blog of our hosting brand, aWh.
The runner connects outwards to GitLab (it asks over HTTPS whether there is a job to run), so you don’t need to open any inbound port for it. It is enough if it can reach the GitLab instance.
Choosing the executor
The executor determines where and how a job runs. The most common ones:
| Executor | Where does the job run? | When is it a good fit? |
|---|---|---|
shell |
directly on the runner machine, as the gitlab-runner user |
simple deployment scripts on a dedicated machine |
docker |
each job in a fresh Docker container | in most cases; this is our default choice |
kubernetes |
in pods in a Kubernetes cluster | if you already have a cluster and need to scale |
docker-autoscaler |
on cloud machines started on demand | for variable, heavy workloads |
The advantage of the Docker executor is that every job starts in a clean environment, the tools it needs come with the image the job specifies, and the jobs don’t clutter up the runner machine. This is what we set up here.
1. Installing Docker
The Docker executor needs Docker on the machine. We described the installation from the official repository step by step in the aWh knowledge base. To check:
sudo docker run --rm hello-world
2. Installing GitLab Runner
GitLab provides its own package repository, and the install script adds it to the system. The documentation recommends that you review the script before running it:
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" -o script.deb.sh
less script.deb.sh
sudo bash script.deb.sh
sudo apt install gitlab-runner
gitlab-runner --version
systemctl status gitlab-runner
On RHEL-based systems (AlmaLinux, Rocky Linux), use the script.rpm.sh script and dnf install gitlab-runner instead.
The runner’s version should ideally match GitLab’s major and minor version. GitLab.com always runs the latest release (19.4 came out yesterday, 17 September), and the package repository always installs the latest runner to match. With a self-managed GitLab, update the runner together with GitLab.
3. Creating the runner in GitLab
These days you create runners in the GitLab interface, and you get a runner authentication token for each one, starting with the glrt- prefix. The old project- or group-level registration token is deprecated, and GitLab plans to remove it in version 20.0; don’t use it for new runners.
For a project runner:
- Open the project, then Settings › CI/CD, and expand the Runners section.
- Select Create project runner.
- Enter the tags, for example
docker, linux. With these you can specify in.gitlab-ci.ymlwhich jobs should run on this runner. If it should also run untagged jobs, tick the Run untagged jobs option. - Enter a description, then Create runner.
- On the next page you get the registration command with the token. You only see the token for a short time, so use it straight away.
You can create a group runner in the group under Build › Runners, and one for the whole instance under Admin › CI/CD › Runners.
In the new workflow, the tags, the range of jobs it can run and the maximum job timeout are set in the GitLab interface, not in the registration command.
4. Registering on the server
sudo gitlab-runner register \
--non-interactive \
--url "https://gitlab.com" \
--token "glrt-..." \
--executor "docker" \
--docker-image "alpine:latest" \
--description "docker-runner-01"
With a self-managed GitLab, --url is the address of your own instance. To check:
sudo gitlab-runner list
sudo gitlab-runner verify
On the project’s Settings › CI/CD › Runners page, a green indicator should appear next to the runner.
5. Fine-tuning config.toml
The settings are in the /etc/gitlab-runner/config.toml file. A useful starting point:
concurrent = 4 # this many jobs can run on the machine at once
check_interval = 3
[[runners]]
name = "docker-runner-01"
url = "https://gitlab.com"
token = "glrt-..."
executor = "docker"
[runners.docker]
image = "alpine:latest"
privileged = false
pull_policy = ["if-not-present"]
volumes = ["/cache"]
shm_size = 268435456
Adjust the concurrent value to the machine’s resources: on a 4 vCPU machine, 2–4 parallel jobs is realistic. The runner detects changes by itself, but a sudo gitlab-runner restart doesn’t hurt either.
Building Docker images in the pipeline
If you build Docker images in your jobs, there are two ways. Docker-in-Docker (the docker:dind service) requires the privileged = true setting, which effectively gives the job root access on the runner machine. Mounting the host’s Docker socket (/var/run/docker.sock) is just as risky. A safer alternative is rootless image building, for example with Buildah or BuildKit’s rootless mode. Only assign a privileged runner to projects you trust.
6. The first job
The .gitlab-ci.yml in the root of the project:
test:
image: php:8.4-cli
tags:
- docker
script:
- php -v
- php -l index.php
After a push, you can see on the Build › Pipelines page whether the job runs on your own runner.
Security and maintenance
- Don’t run untrusted code with the shell executor. With the shell executor, anyone who can start a pipeline can run commands on the runner machine.
- Protected runner, protected variables. Mark the runners that do deployments as protected, so only pipelines on protected branches (for example
main) can use them, and secret variables can’t leak out from an arbitrary branch. - One runner, one purpose. The runner with access to production deployments should be separate from the one running development jobs.
- Clean-up. Docker images and the cache fill up the disk within weeks. A weekly
docker system prunesolves this. You can schedule it with a systemd timer or a crontab entry; we described the crontab syntax in the aWh knowledge base. - Updates. Update the runner together with the system updates (
sudo apt update && sudo apt install gitlab-runner).
If you manage several runners or several environments, it’s worth building the runner machine from code too: the virtual machine with Terraform or OpenTofu, for example, and the installation and config.toml with Ansible.
We also help with building and operating CI/CD environments, GitLab runners and deployment processes; you can read more on our Cloud and DevOps page.