Self-hosted CI runners: Part 1 · Part 2
A pipeline on GitLab's hosted runners starts every job on a fresh machine. The job waits in a queue, pulls its image, downloads the cache archive, runs, and uploads the cache again. On GitLab.com the running part is billed in compute minutes. The deploy job then connects to your server from an address you do not control, so the SSH port has to be reachable from the internet. This site's .gitlab-ci.yml does exactly that: the deploy template runs ssh-keyscan -p $SSH_PORT $SSH_HOST and scp from a hosted runner.
A runner on your own VPS changes all three: images and dependency caches stay warm on local disk, you pay for a server instead of minutes, and a deploy job can reach production over a private network. The price is a machine that executes pipeline code with your CI secrets in its environment. Isolation and least privilege are therefore part of the setup from step one.
What you gain and what you take on
You gain warm image layers, a cache volume that survives between jobs, no per-minute billing and access to private hosts. You take on a server to patch, a disk that fills with images and cache volumes, a runner version to keep in step with GitLab, and a Docker daemon that is root on that host. If nobody on the team will do those chores every month, stay on hosted runners.
Requirements
- GitLab with runner authentication tokens. Runners are created in the UI and registered with a token that starts with
glrt-. The old registration tokens were disabled in GitLab 17.0 and are scheduled for removal in GitLab 20.0, so new setups should not use them. Keep the runner'smajor.minorin step with GitLab's; GitLab guarantees backward compatibility between minor updates. This guide pinsgitlab/gitlab-runner:alpine-v19.5.3, current on 2026-11-10. - A Linux host with Docker Engine. GitLab publishes no fixed CPU or RAM numbers. Its requirements page lists what sizing depends on: CPU and memory used by jobs, the number of concurrent jobs, projects and developers. A workable starting point: size the box for
concurrentmultiplied by your heaviest job. In this repository that istest:php, which runsnpm run buildand then Pest with--parallel. - Outbound HTTPS only. The runner opens the connection: it polls GitLab with
POST /api/v4/jobs/request. It needs outbound access to your GitLab instance and to the image registries your jobs use. It needs no inbound port, so the firewall can deny all incoming traffic except your own SSH. - A machine of its own. GitLab recommends a host separate from the GitLab instance and its security page recommends a separate network segment for runners. Do not put the runner on the production application server: a job that escapes its container would land next to the production database.
Step 1: create the runner in the UI
In the project go to Settings > CI/CD, expand Runners and select Create project runner. Set the tags, decide on Run untagged, and create it. GitLab shows a glrt- token and the command to register. Store it in a password manager. Tags, run untagged, the protected flag and the maximum job timeout are now set in the UI. With --token, gitlab-runner register does not accept those values on the command line.
Step 2: compose file and registration
Run the runner itself in a container. The config directory is mounted so config.toml survives upgrades, and the Docker socket is mounted so the runner can start job containers:
services:
gitlab-runner:
image: gitlab/gitlab-runner:alpine-v19.5.3
restart: unless-stopped
volumes:
# config.toml lives here and holds the runner token: chmod 600, never in git
- ./config:/etc/gitlab-runner
# lets the runner start job containers on this host's Docker daemon
- /var/run/docker.sock:/var/run/docker.sock
ports:
# Prometheus metrics, reachable from this host only
- "127.0.0.1:9252:9252"
Register once with a throwaway container of the same service, so the result lands in the mounted ./config:
export RUNNER_TOKEN='glrt-...' # from the UI, never committed
docker compose run --rm gitlab-runner register \
--non-interactive \
--url "https://gitlab.com" \
--token "$RUNNER_TOKEN" \
--executor docker \
--docker-image alpine:3.22 \
--description "vps-runner-1"
chmod 600 config/config.toml
docker compose up -d
GitLab's install page warns that the socket mount gives the runner container full control of the host's Docker daemon. That is acceptable only because this host runs nothing else.
Step 3: the config.toml keys that matter
Registration writes a minimal file. Edit it to this shape, then docker compose restart gitlab-runner:
concurrent = 2
check_interval = 3
listen_address = ":9252"
[[runners]]
name = "vps-runner-1"
url = "https://gitlab.com"
token = "glrt-REPLACE_ME"
executor = "docker"
limit = 2
request_concurrency = 2
output_limit = 8192
[runners.docker]
image = "alpine:3.22"
privileged = false
volumes = ["/cache"]
pull_policy = ["always", "if-not-present"]
allowed_pull_policies = ["always", "if-not-present"]
memory = "4g"
cpus = "2"
concurrentis the global cap on jobs running at once;limitcaps one[[runners]]entry. Size them with the rule above.request_concurrencydefaults to 1. With that default andlimit = 2, runner 19.5.3 logs a long polling warning at startup and suggests 2 to 4.privileged = falsekeeps containers isolated. GitLab's security page says privileged jobs can gain root on the host.volumes = ["/cache"]keeps the local cache in a Docker volume between jobs.pull_policydefaults toalways. With a list, the runner tries the next policy when a pull fails, so a registry outage does not stop the pipeline. Unchanged layers are not downloaded again either way.if-not-presenton its own lets a job use a cached private image without credentials, which GitLab warns against on runners shared by different users.allowed_pull_policiesstops a job from requesting a policy you did not list.allowed_imagesandallowed_servicesrestrict images and services the same way, with wildcards.memoryandcpusstop one runaway job from starving the other one.
Executor: docker, not shell
The shell executor is in maintenance mode. It reuses the host for every build, has no clean environment per job, and gives jobs the file system access of the runner user. GitLab's security page calls it a high risk for the host and network. Use the docker executor: a fresh container per job, services such as the redis:latest this repository's test:php job uses, and no access to the runner's files by default.
Building Docker images: choose the least privilege that works
This site's pipeline builds a tarball, not an image, so its runner stays unprivileged. If your pipeline runs docker build, there are three routes:
- Docker-in-Docker: a
docker:dindservice,privileged = true,volumes = ["/certs/client", "/cache"]andDOCKER_TLS_CERTDIR: "/certs". Each job gets its own daemon. GitLab's docs say privileged mode disables the container's security mechanisms and can lead to container breakout. - Socket binding: add
/var/run/docker.sock:/var/run/docker.sockto the jobvolumes. Jobs then drive the host daemon: their containers are siblings of the runner, and adocker rm -fin a job can remove the runner's containers. Treat it as handing root on the host to every pipeline. - Daemonless builders: Buildah builds OCI images without a daemon, and GitLab documents it with
quay.io/buildah/stable. Kaniko was the usual answer, but Google archived its repository on 3 June 2025, and GitLab's docs now say it is no longer maintained. Check its upstream status on the day before you adopt it or a fork of it.
If you need DinD, give it its own runner: tagged, protected, and preferably on a separate VM.
Tags, run untagged and protected runners
Tags decide which runner takes a job. A runner must have every tag the job lists. A runner that does not run untagged jobs leaves untagged jobs stuck. For this repository, register two runners. The first runs untagged jobs, so test:php, test:js, secrets:gitleaks and build need no change. The second has the tag deploy and is marked Protected, so it only runs jobs on protected branches and tags. Then the deploy template gets one line:
.deploy_template: &deploy_template
stage: deploy
image: alpine:3.19
tags: [deploy]
needs: [build]
deploy_prod runs on main and deploy_dev on develop, so both branches must be protected, or deploy_dev waits for a runner forever. Make SSH_KEY and ENV_FILE protected variables as well, so they never reach an unprotected branch. Once the deploy runner sits in the same private network as production, SSH_HOST can be a private address and the public SSH port can be closed.
Cache: local volume first, S3 when there are two runners
With the Docker executor and no distributed cache, cache: entries are stored under /cache in Docker volumes on the runner host. Fast, but it belongs to that one runner. This repository keys its cache on composer.lock and package-lock.json, so the first pipeline after a lock file change is cold on any runner. Once a second runner or an autoscaler appears, move the cache to S3-compatible storage:
[[runners]]
name = "vps-runner-1"
[runners.cache]
Type = "s3"
Shared = true
[runners.cache.s3]
ServerAddress = "s3.example.com"
BucketName = "gitlab-runner-cache"
BucketLocation = "eu-central-1"
AccessKey = "REPLACE_ME"
SecretKey = "REPLACE_ME"
Local volumes and images grow without limit. GitLab ships clear-docker-cache for unused runner volumes and suggests running it weekly from cron. It does not remove images; docker system prune does. Every prune makes the next pipeline cold, so schedule it outside working hours.
Measure it on your own pipeline
Numbers from someone else's pipeline say little about yours, so measure your own. The Jobs API returns queued_duration (time waiting for a runner) and duration (time running) per job.
curl --silent --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
"https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines/$PIPELINE_ID/jobs" \
| jq -r '.[] | [.name, .runner.description, .queued_duration, .duration] | @tsv'
Compare three pipelines on the same commit: on hosted runners, on your runner right after a lock file change (cold cache), and a retry on your runner (warm cache). queued_duration shows the queue you no longer wait in. The gap between cold and warm duration shows what the local cache buys you.
Upgrades and monitoring
Bump the pinned tag when GitLab moves to a new minor version, pause the runner in the UI so no job is running, then docker compose pull && docker compose up -d. Patch the host OS and Docker Engine on the same schedule.
With listen_address set, the runner serves Prometheus metrics on /metrics, port 9252 by default. The endpoint has no authentication. The compose file therefore publishes it on 127.0.0.1 only. Scrape it from a Prometheus on the same host or over a private network, alert when the target is down, and watch gitlab_runner_errors_total. The runner list in GitLab also shows the last contact time of each runner.
When not to self-host
- Low build volume. A few pipelines a week fit in the hosted runners.
- Nobody owns the box. An unpatched runner with deploy secrets is worse than slow CI.
- Public projects or forks. Pipeline code from strangers runs on your server and can read what the job can read. Use hosted runners or ephemeral VMs.
- Burst concurrency or many platforms. One VPS gives a fixed number of slots on one architecture. Autoscaling executors exist, but that is a different project.
If you want a runner like this set up and hardened for your team's GitLab, see what I offer. The reasoning above pairs with the hard CI gates from the quality gates post.
Next part: GitHub Actions self-hosted runners without handing out root.
Sources
- GitLab Runner docs: Run GitLab Runner in a container (accessed 2026-11-10)
- GitLab Runner docs: Registering runners (accessed 2026-11-10)
- GitLab docs: Migrating to the new runner registration workflow (accessed 2026-11-10)
- GitLab docs: Manage runners (runner scopes) (accessed 2026-11-10)
- GitLab docs: Configuring runners (protected runners, tags, timeouts) (accessed 2026-11-10)
- GitLab Runner docs: GitLab Runner overview and version compatibility (accessed 2026-11-10)
- GitLab Runner docs: System requirements and supported platforms (accessed 2026-11-10)
- GitLab Runner docs: Executors (accessed 2026-11-10)
- GitLab Runner docs: Docker executor (accessed 2026-11-10)
- GitLab Runner docs: Advanced configuration (accessed 2026-11-10)
- GitLab docs: Use Docker to build Docker images (accessed 2026-11-10)
- GitLab docs: Use Docker-in-Docker (accessed 2026-11-10)
- GitLab docs: Use kaniko to build Docker images (removed) (accessed 2026-11-10)
- GoogleContainerTools/kaniko repository (archived) (accessed 2026-11-10)
- GitLab Runner docs: Security for self-managed runners (accessed 2026-11-10)
- GitLab Runner docs: Monitor GitLab Runner usage (accessed 2026-11-10)
- GitLab docs: Jobs API (accessed 2026-11-10)
- Docker Hub: gitlab/gitlab-runner tags (accessed 2026-11-10)