Self-Hosted GitLab Runners: Install, Caching, and Scaling

The old registration token is going away — the registration-token flow (--registration-token with --tag-list on the command line) is deprecated. With a glrt- token, tags, run-untagged and locked are managed in the UI, not with register flags.

Config lives in one file — runners registered with sudo write to /etc/gitlab-runner/config.toml. The service watches it and reloads on change, so most edits need no restart.

Default to docker — each job starts clean from the image named in the job, so builds are reproducible and one job cannot break the next. Generate a solid build image with the Dockerfile generator and pin it in .gitlab-ci.yml.

Never share a privileged runner — Docker-in-Docker needs privileged = true, and a privileged container can mount the host filesystem. Keep such runners project-specific and protected, or build images with rootless tools like BuildKit rootless, Buildah or Kaniko instead.

docker+machine is end-of-life — the old Docker Machine autoscaler is deprecated in favour of docker-autoscaler and instance executors built on GitLab's fleeting plugins. Plan new setups on the new executors.

Size concurrent to the host — a rough start is one concurrent job per two vCPUs for compile-heavy work, then adjust from load average and job duration. Too many parallel builds on one disk is slower than fewer.

pull_policy matters for speed and trust — if-not-present reuses images already on the host, which is fast but means a job can run an image some other job pulled. On shared runners, use always, or allowed_pull_policies to restrict what jobs may request.

Clean up Docker storage — the docker executor leaves cache volumes and images behind. The package ships /usr/share/gitlab-runner/clear-docker-cache; run it weekly from a systemd timer before the disk fills.

Cache paths must be inside the project — GitLab only caches paths under CI_PROJECT_DIR, which is why the example redirects npm's cache there instead of caching ~/.npm.

Key on the lockfile — key:files hashes up to two files into the cache key, so the cache changes exactly when dependencies change. Add fallback_keys so a new branch starts from the default branch's cache instead of empty.

Use pull in fan-out jobs — if ten parallel test jobs all upload the same cache with pull-push, you pay ten uploads for one useful write. Let one job write and the rest read.

More static hosts — register the same runner token on several machines, or create separate runners per host with distinct tags. Combine with the shared S3 cache so it does not matter which host picks up a job.

docker-autoscaler — a small manager host creates cloud instances through an autoscaling group (AWS, Google Cloud, Azure) and runs Docker jobs on them. Idle capacity is kept warm by policy and scaled to zero off-hours.

Kubernetes executor — install the gitlab/gitlab-runner Helm chart and each job becomes a pod. Scaling is the cluster autoscaler's job, which is a good fit if you already operate a cluster.

Scale on metrics, not guesses — add listen_address = ":9252" at the top of config.toml to expose Prometheus metrics. gitlab_runner_jobs shows running jobs per runner; compared with concurrent, it tells you whether you are short of capacity or just have slow jobs.

max_use_count = 1 is the safe default — a fresh instance per job means nothing from one job can leak into the next, at the cost of boot time. Raise it only for trusted projects.

Infrastructure as code — keep the autoscaling group, launch template and bucket in Terraform; the Terraform generator gives a starting point. For the Helm route, the Kubernetes generator helps with namespace quotas.

Protect deploy runners — mark runners that hold deployment credentials as protected, so they only pick up jobs from protected branches and tags. A merge request from a fork then cannot run on them.

Upgrade with GitLab — keep the runner's major.minor version close to your GitLab server's. Pause the runner in the UI and let running jobs finish, then apt upgrade or dnf upgrade gitlab-runner and run gitlab-runner verify.