GitLab itself never runs your scripts. It keeps a queue of jobs, and runners come and ask for work. A runner is a small Go program, gitlab-runner, that polls GitLab, takes a job, prepares an environment, runs the script and sends back the log and the result. Understanding runners explains why jobs sit in pending, why some jobs can build Docker images and others cannot, and how to keep secrets safe.
How a job reaches a runner
GitLab Runner
pipeline created
job queued (tags: docker) ◀── polls: "anything for me? I have tags docker, linux"
job assigned ──▶ creates container from job image
clones repo, downloads artifacts, restores cache
runs before_script, script, after_script
log and status stored ◀── streams log, uploads artifacts and cache
Runners only make outgoing connections to GitLab. They work behind a firewall or NAT, as long as they can reach your GitLab URL over HTTPS.
Hosted runners on GitLab.com
On GitLab.com you already have runners: GitLab-hosted machines that run untagged jobs on Linux by default. Each job gets a fresh, short-lived virtual machine that is deleted afterwards, so nothing leaks between jobs or customers.
- Jobs consume compute minutes from your namespace’s monthly allowance. Larger machine sizes consume minutes faster.
- You pick a bigger machine or another OS with tags, for example
saas-linux-medium-amd64orsaas-linux-small-arm64. The current list of sizes is on the Hosted runners page of the GitLab docs. - Docker-in-Docker works out of the box, which you will use in lesson 8.
For many teams hosted runners are enough forever. You run your own when you need private network access (a database in your VPC), special hardware (GPUs, more memory), cheaper minutes at scale, or a self-managed GitLab.
Runner scopes
| Scope | Who can use it | Created in |
|---|---|---|
| Instance runner | Every project on the GitLab instance | Admin area (self-managed) or GitLab-hosted on GitLab.com |
| Group runner | Every project in a group and its subgroups | Group → Build → Runners |
| Project runner | One project, or a few you enable it for | Project → Settings → CI/CD → Runners |
On GitLab.com you create group and project runners yourself. A group runner is usually the right choice: one runner fleet for all of Orbit’s repositories.
Executors: how a runner runs a job
The executor decides what kind of environment each job gets:
| Executor | Each job runs in… | Good for | Watch out for |
|---|---|---|---|
| Shell | A shell directly on the runner host | Quick experiments, very special hosts | No isolation, jobs share files and tools |
| Docker | A new container from the job’s image | Most teams, clean and repeatable | Building images needs extra setup |
| Docker Autoscaler | Containers on cloud VMs created on demand | Bursty workloads, cost control | More moving parts |
| Instance | A whole cloud VM created on demand | Jobs that need a full machine | Slower start |
| Kubernetes | A pod in a cluster | Teams already on Kubernetes | Cluster permissions, resource limits |
| Custom | Whatever your scripts do | Unusual platforms | You maintain it |
The Docker executor is the default choice: every job starts from the image in your YAML, so the job behaves the same on any runner.
Run your own runner with Docker
Let us add a group runner for Orbit on a Linux machine with Docker installed. A cheap VM is plenty.
1. Create the runner in GitLab
In your group, open Build → Runners → New group runner:
- Add tags
dockerandorbit. - Leave Run untagged jobs unticked so only jobs that ask for these tags land here.
- Select Create runner.
GitLab shows a runner authentication token that starts with glrt-. Copy it now; it is shown once.
Registration tokens are deprecated. Older guides use a project-wide registration token with gitlab-runner register --registration-token. Since GitLab 16 you create the runner in the UI (or API) first and register with its own glrt- authentication token. That ties every runner to a record with an owner, tags and settings you can audit.
2. Start the runner container
$ sudo mkdir -p /srv/gitlab-runner/config
$ sudo 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:latest
The runner stores its configuration in /srv/gitlab-runner/config/config.toml on the host, so it survives upgrades. Mounting the Docker socket lets it start a container for each job on the same host. In production, pin the image to a version that matches your GitLab major version instead of latest.
3. Register it
$ sudo docker exec -it gitlab-runner gitlab-runner register \
--non-interactive \
--url "https://gitlab.com" \
--token "glrt-xxxxxxxxxxxxxxxxxxxx" \
--executor "docker" \
--docker-image "alpine:3" \
--description "orbit-docker-01"
Runtime platform arch=amd64 os=linux
Verifying runner... is valid
Runner registered successfully.
Back in GitLab, the runner shows a green dot under Build → Runners. Tags, protection and “run untagged” are configured in the UI now, not on the command line.
4. Send a job to it
which-runner:
tags: [docker, orbit]
script:
- echo "Running on $CI_RUNNER_DESCRIPTION"
- cat /etc/os-release
A job is picked up only by a runner that has all the job’s tags. A job with no tags goes to runners that accept untagged jobs.
config.toml essentials
concurrent = 4
check_interval = 0
[[runners]]
name = "orbit-docker-01"
url = "https://gitlab.com"
token = "glrt-xxxxxxxxxxxxxxxxxxxx"
executor = "docker"
limit = 4
[runners.docker]
image = "alpine:3"
privileged = false
pull_policy = ["if-not-present"]
volumes = ["/cache"]
memory = "2g"
cpus = "2"
| Setting | Meaning |
|---|---|
concurrent | Maximum jobs across all runner entries in this file |
limit | Maximum jobs for this entry |
image | Default image when a job sets none |
privileged | Needed for Docker-in-Docker; gives containers wide host access |
pull_policy | always is safest for shared runners; if-not-present is faster |
volumes | Extra mounts; /cache holds local caches between jobs |
memory / cpus | Resource limits per job container |
The runner reloads config.toml automatically when it changes. Restart it with docker restart gitlab-runner after upgrades.
Keeping runners secure
A runner executes whatever code is in the branch. Anyone who can push can make it run anything. Treat runners as part of your security boundary:
- Protected runners only take jobs from protected branches and tags. Use them for deploy jobs that reach production networks or hold cloud permissions.
- Separate fleets: one runner group for untrusted merge request jobs, another for deploys.
- **Avoid
privileged = true** on shared runners. A privileged container can take over the host. Prefer daemonless image builds (lesson 8) or dedicated runners for Docker builds. - Mounting the Docker socket into job containers is equivalent to root on the host. Do it only on runners dedicated to one trusted project.
- Ephemeral beats long-lived: autoscaling executors that destroy the VM after each job leave nothing behind for the next job.
- Keep it updated, and rotate the runner token if a host is compromised (delete the runner and create a new one).
Troubleshooting
| Symptom | Likely cause |
|---|---|
| Job stuck in pending with “no active runners” | No online runner has all the job’s tags, or runners do not accept untagged jobs |
| Job pending only on protected branches | The runner is protected and the branch is not, or the opposite |
Cannot connect to the Docker daemon | Docker-in-Docker service missing or runner not privileged (lesson 8) |
| Runner shows never contacted | Wrong URL or token, or the host cannot reach GitLab over HTTPS |
| Jobs much slower than expected | concurrent = 1, pull_policy = always with large images, or no cache volume |
Check the runner side with docker logs gitlab-runner and gitlab-runner verify.
Exercise
A job has tags: [docker, gpu]. Your only runner has tags docker and linux. What happens?
Show answer
Answer: B. Runners pick jobs whose tags are a subset of their own. A runner with docker and linux cannot take a job that also needs gpu.
Exercise
Which runner setup is best for the production deploy job that holds cloud permissions?
Show answer
Answer: C. Protected runners refuse jobs from unprotected branches, so a feature branch cannot borrow the runner’s network access or cloud identity. Manual jobs can still be clicked by developers.
Key takeaways
- Runners poll GitLab for jobs; GitLab never connects to them.
- Hosted runners on GitLab.com need no setup; run your own for private networks, special hardware or cost.
- The Docker executor gives each job a clean container from the job’s image.
- Create runners in the UI and register them with their
glrt-authentication token. - Tags route jobs; protected runners keep deploy power away from feature branches.
FAQ
Do I need my own runner to follow this course?
No. Hosted runners on GitLab.com handle every lesson. Running your own is useful practice and needed when jobs must reach private networks.
How many jobs can one runner run at once?
As many as concurrent allows and the machine can handle. A rule of thumb for the Docker executor is one job per CPU core, adjusted after watching real workloads.
Can one machine host several runners?
Yes. Each [[runners]] entry in config.toml is a separate runner with its own token, tags and executor, all managed by one gitlab-runner process.
Should I use the Kubernetes executor?
If your team already runs Kubernetes, it gives you autoscaling and resource limits for free. If not, the Docker or Docker Autoscaler executor is far simpler to operate.
How do I upgrade a runner?
Pull the new image and recreate the container with the same config volume, or upgrade the package on the host. Keep the runner’s major version close to your GitLab version.