GitLab runners: hosted vs self-hosted
A GitLab runner is the machine that runs a CI/CD job. GitLab Runner, a free program, takes jobs from GitLab and runs them, and the tags: on a job decide which runner gets it. You can use GitLab.com's hosted runners and pay in compute minutes, run your own, or use a runner from another company.
What a runner is
GitLab itself does not run your jobs. A runner asks GitLab for work, runs the job's script, and sends the log and the result back. Each runner is registered to an instance, a group or a project, and it has tags. A job runs on a runner that has every tag the job lists.
On GitLab.com, jobs with no tags go to GitLab's hosted runners, if they are on for the project. Jobs on those runners use compute minutes. Jobs on your own project or group runners do not.
Hosted, self-hosted and third-party
| Kind | Who runs the machine | What it costs | Setup |
|---|---|---|---|
| GitLab.com hosted runners | GitLab | Compute minutes: 400 a month on Free, then $10 per 1,000 | None; on by default |
| Self-hosted runners | You | No GitLab fee; you pay for the machines and their upkeep | Install, register, patch, scale |
| Third-party runners | The provider | Per minute; Groundbox from $0.003 (2 vCPU) | Connect, then change tags: |
Executors
The executor decides what a job runs in. Pick it when you register the runner. From GitLab's executor docs:
| Executor | Each job runs in | Clean for every job | Status |
|---|---|---|---|
| Docker | A container on the runner's host | Yes | Developed |
| Kubernetes | A new pod in your cluster | Yes | Developed |
| Docker Autoscaler | A container on a cloud VM made on demand | Yes | Developed |
| Instance | A whole cloud VM made on demand | Depends on setup | Developed |
| Shell | The host's own shell, as the runner's user | No | Maintenance only |
| SSH | A remote machine over SSH | No | Maintenance only |
| VirtualBox, Parallels | A local VM | Yes | Maintenance only |
| Docker Machine | A container on a VM made by Docker Machine | Yes | Deprecated |
Most teams start with Docker: image: picks the job's container and services: starts databases next to it. The shell executor is the simplest, but every job shares the host, its files and its installed tools.
Install GitLab Runner
On Debian or Ubuntu, from GitLab's package repository:
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" -o script.deb.sh
less script.deb.sh # read it before you run it
sudo bash script.deb.sh
sudo apt install gitlab-runnerRHEL and Fedora use script.rpm.sh and dnf install gitlab-runner. To run the runner itself in a container, with its config on the host:
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:latestOn Kubernetes, with GitLab's Helm chart:
helm repo add gitlab https://charts.gitlab.io
# values.yaml: gitlabUrl: https://gitlab.com/ and runnerToken: glrt-...
helm install --namespace gitlab-runner gitlab-runner -f values.yaml gitlab/gitlab-runnerRegister a runner
In the current workflow, you create the runner in GitLab first, and the machine signs in with its token.
- In the project, go to Settings > CI/CD > Runners > New project runner. For a group, use the group's Build > Runners.
- Add its tags, and choose whether it takes untagged jobs. These are set here now, not on the machine.
- Create it and copy the runner authentication token. It starts with
glrt-. - On the machine, register with that token:
sudo gitlab-runner register \
--non-interactive \
--url "https://gitlab.com/" \
--token "$RUNNER_TOKEN" \
--executor "docker" \
--docker-image alpine:latest \
--description "docker-runner"This writes the runner to /etc/gitlab-runner/config.toml when run as root. With an authentication token, the old flags --tag-list, --run-untagged and --locked are ignored. Registration tokens are deprecated and scheduled for removal in GitLab 20.0. Scripts that still use --registration-token need to move to the new tokens.
Tags
Tags send a job to the right runner: a size, an OS, a GPU, or a machine with access to a private network.
test:
image: node:22
tags: [docker, linux] # only runners with both tags take this job
script:
- npm ci
- npm testA job without tags can run on any runner that takes untagged jobs. If no online runner has all of a job's tags, the job waits in pending until one does.
Concurrency
One gitlab-runner process can run several jobs at once. concurrent at the top of config.toml caps the total, and limit caps each runner:
concurrent = 4 # jobs at once, across every runner in this file
[[runners]]
name = "docker-runner"
url = "https://gitlab.com/"
executor = "docker"
limit = 2 # jobs at once for this runner; 0 means no limit
[runners.docker]
image = "alpine:latest"On a single host, jobs that run together share its CPU, memory and disk. Set concurrent to what the machine can carry, or add machines.
What a self-hosted runner costs
GitLab charges nothing for jobs on your own runners. The cost is the machines and the time spent on them:
- Machines sized for the busiest hour. A fixed fleet sits idle at night and queues jobs at peak. Autoscaling fixes that but is a project of its own.
- Upkeep. Updates to GitLab Runner, Docker and the OS. Disks fill with images and build output and need pruning.
- Clean jobs. With the shell executor, or Docker with a shared socket or privileged mode for docker-in-docker, one job can see or change what the next one runs on.
- Autoscaling. The Docker Machine executor was deprecated in GitLab 17.5 and is scheduled for removal in GitLab 20.0 (May 2027). Setups built on it need moving to the Docker Autoscaler or Instance executor and a fleeting plugin for your cloud.
- Access to GitLab. The runner only makes outgoing requests to GitLab, so it can sit in a private network. That is the main reason to self-host when jobs must reach internal systems.
GitLab.com hosted runners and compute minutes
GitLab's hosted Linux runners give each job a new VM. Pick a size with its tag; jobs with no tag use small. Each size has a cost factor: a job uses its minutes times the factor in compute minutes. At $10 per 1,000 extra compute minutes, that is the price per minute below.
| Tag | Size | Cost factor | GitLab.com per minute | Plans | Groundbox per minute |
|---|---|---|---|---|---|
saas-linux-small-amd64 | 2 vCPU, 8 GB | 1 | $0.010 | All | $0.003 |
saas-linux-medium-amd64 | 4 vCPU, 16 GB | 2 | $0.020 | All | $0.006 |
saas-linux-large-amd64 | 8 vCPU, 32 GB | 3 | $0.030 | Premium, Ultimate | $0.011 |
saas-linux-xlarge-amd64 | 16 vCPU, 64 GB | 6 | $0.060 | Premium, Ultimate | $0.021 |
saas-linux-2xlarge-amd64 | 32 vCPU, 128 GB | 12 | $0.120 | Premium, Ultimate | not offered |
| GitLab plan | Price | Compute minutes a month |
|---|---|---|
| Free | $0 | 400 |
| Premium | $29 per user a month, billed yearly | 10,000 |
| Ultimate | custom pricing | 50,000 |
When a namespace has used its compute minutes for the month, GitLab's instance runners stop taking new jobs. Project and group runners are not affected by the quota. Usage resets to 0 each month. Public projects in the GitLab for Open Source program use a cost factor of 0.5. New users on the Free plan may be asked to verify their identity, by email, phone or card, before pipelines run. We were asked even with our own runners, so do it before you count on a pipeline.
Work out a month for your own numbers with the GitLab compute minutes calculator.
Runners with no machines to run: Groundbox
Groundbox runs GitLab Runner for you. Each job gets a fresh VM that is destroyed when it ends, billed by the second. Jobs on Groundbox are project or group runners to GitLab, so they do not use compute minutes. It works with gitlab.com and with self-managed GitLab that is reachable over HTTPS from the internet.
- In the dashboard, open Repos and runners > GitLab. Click Connect GitLab for gitlab.com, or paste a
glrt-token from any GitLab. - Change the job's
tags:to a size: groundbox-2vcpu, groundbox-4vcpu, groundbox-8vcpu, groundbox-16vcpu, orgroundboxto pick a size from the job's earlier runs.
test:
image: node:22
tags: [groundbox-4vcpu] # was: [saas-linux-medium-amd64]
script:
- npm ci
- npm testimage: and services: work the way GitLab's Docker executor runs them. The log, artifacts and cancel button stay in GitLab. Not there yet for GitLab jobs: cache: across jobs (each job starts on a clean VM), and our live logs, terminal and test insights, which are for GitHub Actions jobs for now. We have to reach your GitLab over the internet, so a self-managed GitLab behind a VPN does not work yet. Setup step by step: GitLab CI docs. The product page: GitLab runners.
Questions
What is a GitLab runner?
GitLab Runner is the program that takes CI/CD jobs from GitLab and runs them. A runner is one registered copy of it, on a machine that you or GitLab run. The tags on a job decide which runners can take it.
Are GitLab runners free?
GitLab Runner itself is free and open source. GitLab.com's hosted runners use compute minutes: 400 a month on Free, 10,000 on Premium and 50,000 on Ultimate, then $10 per 1,000. Jobs on your own project or group runners do not use compute minutes; you pay for the machines instead.
How do I register a GitLab runner?
Create the runner in GitLab first (Settings > CI/CD > Runners > New project runner), set its tags there, and copy the token that starts with glrt-. Then run gitlab-runner register with --url, --token, --executor docker and --docker-image on the machine. Registration tokens are deprecated and scheduled for removal in GitLab 20.0.
Which GitLab Runner executor should I use?
Docker for most jobs: each job gets a clean container, and image: and services: work. Kubernetes if you already run a cluster. Docker Autoscaler or Instance to add cloud VMs as jobs come in. Shell runs jobs straight on the host, and files from one job are still there for the next.
How do GitLab runner tags work?
A job with tags: [docker, linux] only runs on a runner that has every one of those tags. A runner can also be set to take untagged jobs or not. With the current workflow, tags are set on the runner in GitLab, not with gitlab-runner register.
How many jobs can one GitLab runner run at once?
The concurrent setting at the top of config.toml caps jobs across every runner in that file, and limit caps a single runner. Past that, the machine's CPU and memory are the limit: jobs that share a host slow each other down.
Is the Docker Machine executor deprecated?
Yes. The Docker Machine executor was deprecated in GitLab 17.5 and is scheduled for removal in GitLab 20.0 (May 2027). GitLab points users to the Docker Autoscaler and Instance executors, which add and remove cloud VMs through fleeting plugins.
How do I run GitLab CI jobs without running my own machines?
Use GitLab.com's hosted runners, or a third-party runner. On Groundbox you connect GitLab and set tags: [groundbox-4vcpu] on a job. Each job gets a fresh VM, billed by the second at $0.006 a minute for 4 vCPU, and it does not use GitLab compute minutes.
Sources
Checked on 2026-11-20, on each company's own pages. Prices change; their pages are the final word.
- GitLab: Pricing
- GitLab: Compute minutes
- GitLab: Compute usage for instance runners
- GitLab: Hosted runners on Linux
- GitLab: Install GitLab Runner from the official repositories
- GitLab: Run GitLab Runner in a container
- GitLab: GitLab Runner Helm chart
- GitLab: Registering runners
- GitLab: Executors
- GitLab: Docker Machine executor
- GitLab: Advanced configuration (config.toml)
- GitLab: Debugging CI/CD pipelines (identity verification)
Related
- GitLab runners: Fast GitLab CI runners: change tags in .gitlab-ci.yml and each job gets a fresh VM, billed by the second, at about a third of GitLab.com's hosted runner price. gitlab.com and self-managed.
- GitLab compute minutes: How GitLab.com prices hosted runners: compute minutes per plan, cost factors by size, what extra minutes cost, and a calculator next to Groundbox's per-second price.
- GitLab CI: Run GitLab CI jobs on Groundbox: connect GitLab or paste a runner token, set tags: [groundbox-4vcpu], and each job gets a fresh VM, billed per second. gitlab.com and self-managed.
- GitHub Actions runners: What a GitHub Actions runner is, the four kinds you can use, what each costs per minute, and measured job times on GitHub-hosted and Groundbox runners.
- Pricing: Free: 3,000 CI minutes a month, no card. Paid: $20 a month with $20 of usage included. CI from $0.003 a minute, sandboxes $0.04 per vCPU-hour.
Try it: sign in with GitLab, GitHub, Google or email, then open Repos and runners › GitLab. The free plan needs no card.