GitLab Runners

GitLab Runners are lightweight agents that execute the jobs defined in your CI/CD pipelines. Every time you push code and a pipeline is created, GitLab needs something to actually run the jobs — compile the code, run the tests, build the images, deploy the application. That's the runner's job. Without a runner, a pipeline is just a definition; the runner is what brings it to life.

What makes runners special is their architectural flexibility. They run outside GitLab itself, on infrastructure you control or that GitLab.com provides. This means you decide where your jobs execute: on your own servers, in your private data center, in a cloud VM, inside a Kubernetes cluster, or on GitLab's shared infrastructure. You also decide what environment the jobs run in: a container, a shell, a VM, or a pod. This separation between GitLab (the orchestrator) and the runner (the executor) is a fundamental design decision that gives GitLab CI/CD enormous flexibility.

Runners are also the primary place where security and isolation matter. Since runners execute arbitrary code from your repository, they need to be isolated from each other and from the host they run on. Modern runners use containers and Kubernetes pods to provide this isolation. Understanding runners — their types, executors, and configuration — is essential for running pipelines safely and efficiently at scale.

GitLab organizes runners into three scopes: shared, group, and project. Each scope determines who can use the runner and how it's managed. Choosing the right scope is a balance between convenience (shared runners require no setup) and control (project runners give you complete isolation and customization).

The scope determines which jobs a runner can pick up. A shared runner serves every project in the GitLab instance that has shared runners enabled. A group runner serves every project within a specific group (and its subgroups). A project runner serves only one project. This hierarchy means you can start with shared runners for simplicity and graduate to group or project runners as your needs become more specialized.

GitLab Runner is a single binary that can be installed on Linux, macOS, Windows, or as a container. For most production use cases, installing it as a package (deb/rpm) on a dedicated host, or running it as a container, is the recommended approach. The container approach is particularly elegant because it keeps the runner itself isolated from the host and makes updates trivial.

The installation method you choose affects how the runner is managed (systemd, Homebrew services, Docker restart policies) and how it's upgraded. For production, always install from the official GitLab repository rather than downloading binaries manually — this ensures you get security updates through your normal package manager. The installer script detects your operating system and configures the correct repository automatically.

After installing the runner binary, you need to register it with GitLab. Registration is the process of linking a runner to a specific GitLab instance and scope, and it's how the runner obtains the credentials it uses to pick up jobs. Without registration, the runner doesn't know which GitLab server to talk to or which jobs it's allowed to run.

Registration requires a registration token, which you obtain from GitLab. The token encodes the scope (instance, group, or project) — a token from a project's settings only lets you register a project runner, a token from a group's settings only lets you register a group runner, and so on. Tokens are sensitive: anyone with a registration token can register a runner, so treat them like secrets.

During registration, you specify the executor (docker, shell, kubernetes, etc.) and answer a few setup questions. The runner then generates a config file (/etc/gitlab-runner/config.toml) containing its configuration and authentication tokens. After registration, the runner appears in the GitLab UI under Settings → CI/CD → Runners, and it can start picking up jobs.

The runner's behavior is controlled by /etc/gitlab-runner/config.toml, which is generated during registration and can be edited to tune performance and behavior. This file has two parts: a top-level section with global settings and a [runners] array containing one entry per registered runner.

The most important global setting is concurrent, which controls how many jobs can run simultaneously on this runner. Setting this higher lets you run more jobs in parallel, but it also uses more resources — so it should be tuned to match your host's capacity. Each runner entry also has its own executor-specific configuration: for Docker, this includes the default image, privileged mode, and volume mounts; for Kubernetes, this includes namespace, CPU/memory limits, and pod labels.

Editing config.toml while the runner is running is safe — the runner watches the file and reloads on changes. This means you can tune configuration without restarting the service. Just be careful to keep the TOML valid; a syntax error will prevent reload and the runner will keep using the old configuration until the file is fixed.

Tags are the mechanism that decides which runner picks up a specific job. When a job declares tags, GitLab will only assign it to runners that have all the same tags. This is how you route jobs to specific infrastructure — for example, sending GPU-intensive jobs to a runner that has the gpu tag, or sending deployment jobs to a runner that has network access to production.

If a job has no tags, it can be picked up by any runner that has run_untagged: true. This is fine for simple pipelines, but in a multi-runner environment it can lead to jobs landing on the wrong runner — for example, a build job meant for a specialized runner being picked up by a shared one. The discipline of using tags consistently is what makes multi-runner setups predictable.

A runner can have multiple tags, and can be configured to run untagged jobs or only tagged jobs. A common pattern is to tag runners by environment (staging, production), by capability (docker, gpu, arm64), or by team (backend, frontend). Jobs then declare exactly which tags they need, and GitLab handles the routing.

Runners execute code from your repository, which means they're a potential attack vector. A compromised runner can access the secrets it handles, attack the host it runs on, and pivot to other resources in your infrastructure. For this reason, runners should be treated as untrusted infrastructure and hardened accordingly.

The most important security control is isolation. Using the Docker or Kubernetes executor means each job runs in its own container or pod, isolated from other jobs and from the host. If you use the shell executor, jobs run directly on the host with the runner user's permissions, which is much harder to secure. Modern deployments should use Docker or Kubernetes executors almost exclusively.

Beyond isolation, several other controls matter: protected runners (only on protected branches), ephemeral runners (created for a single job and destroyed after), and limited runner permissions (least privilege). In high-security environments, you might use one runner per project, run it in a dedicated VM or namespace, and destroy it after each use. This is what GitLab's "runners autoscaling" and "ephemeral runners" features provide.