Lesson 05 intermediate

GitLab Runners

What a runner is and how it picks up jobs, hosted runners on GitLab.com, instance, group and project runners, executors compared, installing your own runner with Docker, registering it with a glrt- authentication token, tags, config.toml, concurrency and keeping runners secure.

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-amd64 or saas-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

ScopeWho can use itCreated in
Instance runnerEvery project on the GitLab instanceAdmin area (self-managed) or GitLab-hosted on GitLab.com
Group runnerEvery project in a group and its subgroupsGroup → Build → Runners
Project runnerOne project, or a few you enable it forProject → 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:

ExecutorEach job runs in…Good forWatch out for
ShellA shell directly on the runner hostQuick experiments, very special hostsNo isolation, jobs share files and tools
DockerA new container from the job’s imageMost teams, clean and repeatableBuilding images needs extra setup
Docker AutoscalerContainers on cloud VMs created on demandBursty workloads, cost controlMore moving parts
InstanceA whole cloud VM created on demandJobs that need a full machineSlower start
KubernetesA pod in a clusterTeams already on KubernetesCluster permissions, resource limits
CustomWhatever your scripts doUnusual platformsYou 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:

  1. Add tags docker and orbit.
  2. Leave Run untagged jobs unticked so only jobs that ask for these tags land here.
  3. 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"
SettingMeaning
concurrentMaximum jobs across all runner entries in this file
limitMaximum jobs for this entry
imageDefault image when a job sets none
privilegedNeeded for Docker-in-Docker; gives containers wide host access
pull_policyalways is safest for shared runners; if-not-present is faster
volumesExtra mounts; /cache holds local caches between jobs
memory / cpusResource 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

SymptomLikely 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 branchesThe runner is protected and the branch is not, or the opposite
Cannot connect to the Docker daemonDocker-in-Docker service missing or runner not privileged (lesson 8)
Runner shows never contactedWrong URL or token, or the host cannot reach GitLab over HTTPS
Jobs much slower than expectedconcurrent = 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?

  1. The job runs because one of the tags matches
  2. The job stays pending, because a runner must have every tag the job asks for
  3. The job runs on a GitLab hosted runner instead
  4. The tags are ignored and the job runs anywhere
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?

  1. A shared runner with privileged mode and untagged jobs enabled
  2. The developer’s laptop running gitlab-runner with the shell executor
  3. A protected runner with its own tag, so only protected branches like main can use it
  4. Any runner, as long as the deploy job is marked manual
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.

↑ ↓ navigate Enter open Esc close