Manage Runners
Documentation menu

Concepts

Runner states, products and locations, executors, which changes recreate the server, and what you pay for.

Runners and servers

A runner in Manage Runners is a configuration: cloud provider, name, server type, location, executor, concurrency, GitLab host and token, provider token, SSH keys, labels, the cache and the metrics settings. While the runner is active, a server with that configuration exists in your Hetzner project or, as a droplet, in your DigitalOcean account, and runs GitLab Runner. A runner’s provider cannot change.

Every server is created fresh from a Debian 13 image. On first boot it:

  • installs Docker Engine 29 and GitLab Runner from their official package repositories; a GitLab burst runner is ready sooner because it installs GitLab Runner as GitLab’s signed binary, without the package’s prebuilt helper images; with the Docker executor it pulls the helper image on its first job,
  • on DigitalOcean, waits for the runner’s reserved IPs and routes its outgoing traffic through them, except on burst runners, which have none; see Outbound traffic,
  • registers with your GitLab instance using the runner authentication token, with the runner’s cache if it has one,
  • sets GitLab Runner’s global job concurrency,
  • adds swap of a quarter of the memory, at least 2 GiB, for the server’s own services; Docker containers, such as job and service containers, cannot use it,
  • for runners that are not burst runners, turns on automatic package updates, including GitLab Runner and Docker within major version 29, and reboots automatically when an update requires it; GitLab Runner then takes no new jobs and lets the running ones finish for up to 30 minutes before the reboot. Burst runners skip automatic upgrades,
  • allows SSH only for root with a key, never with a password, and enables fail2ban,
  • removes Docker volumes that GitLab Runner created and that are older than 7 days, once a day,
  • installs the collector for metrics, if the runner shows them in the dashboard or sends them to a connection.

Existing servers created without SSH keys before this change may still offer SSH password authentication. Recreating the server, for example by pausing and resuming the runner, turns it off.

Because a paused runner has no server, pausing and resuming always gives you a clean, freshly installed machine. Anything stored on the server’s disk is lost when the server is deleted.

Runner states

State Meaning
Creating The provider is creating the server.
Configuring The server is installing Docker and GitLab Runner.
Active GitLab Runner registered successfully. The runner takes jobs. The API and CLI call this state READY.
Invalid Gitlab Token GitLab rejected the runner token during registration. The server keeps running. Use Fix to enter a new token.
Pausing The runner takes no new jobs and lets its running jobs finish. Then, or at the latest one hour after the pause, the server is deleted and the runner is Paused.
Paused The server is deleted. The configuration and the IP addresses are kept.
Unknown Manage Runners lost track of the server, for example because the provider token stopped working. See Troubleshooting.

A new runner normally goes from Creating through Configuring to Active within a few minutes. Resuming a paused runner takes the same path.

IP addresses

Each runner gets a public IPv4 and IPv6 address: on Hetzner as primary IPs, on DigitalOcean as reserved IPs, through which the droplet also sends its outgoing traffic. When you pause a runner, Manage Runners deletes the server but keeps both addresses, and attaches them to the new server when you resume. Firewall rules and allow lists that mention a runner’s addresses keep working across pause and resume.

The addresses are released only when you delete the runner. A runner’s location cannot be changed, because a different location would change its addresses.

Burst runners added by autoscaling are never paused. On DigitalOcean they get no reserved IPs and use their droplet’s own IPv4 and IPv6 addresses, which go with the droplet.

Products and locations

A product is a Hetzner Cloud server type or a DigitalOcean droplet size. Manage Runners offers every Hetzner server type that Hetzner has not deprecated and that is available in at least one location. Product IDs are the Hetzner server type name with a hz- prefix, for example hz-cpx31, or the DigitalOcean size slug with a do- prefix, for example do-s-2vcpu-4gb; see DigitalOcean setup for the sizes and regions offered there.

Each product shows:

  • Architecture: x86 (Intel or AMD, best compatibility) or, on Hetzner, ARM. Your CI images must support the architecture you choose.
  • vCPUs, RAM and disk.
  • Locations where the provider currently offers it, with the provider’s monthly net list price: Hetzner’s in the currency of Manage Runners’ Hetzner account, DigitalOcean’s in USD.

Hetzner’s locations are Falkenstein and Nuremberg (Germany), Helsinki (Finland), Singapore, and Ashburn and Hillsboro (USA). Not every server type is offered in every location, and availability changes over time. If the provider stops offering a server type in a location, a paused runner using it cannot be resumed until it is available again, and it cannot be duplicated.

Executors

Executor Dashboard label What jobs get
docker docker Each job runs in a container. The default image is alpine:latest; jobs choose their own with image:.
dind docker-in-docker Like docker, with the default image docker:29-cli, privileged containers and the server’s Docker socket mounted, so jobs can build and run images.
shell shell Jobs run directly on the server as the gitlab-runner user.

With shell and dind, jobs have root-equivalent access to the runner’s server, including GitLab Runner’s own configuration. Use the docker executor for code you don’t fully trust.

Docker in dind jobs

A dind job talks to the server’s Docker daemon through the mounted socket, so docker build and docker run work without a service or any variables. Images pulled or built by earlier jobs stay on the server for reuse, and all jobs on the runner share them. Once a day the server removes the build cache and unused images older than 7 days, and it cleans up sooner when less than a quarter of the disk is free.

If a job needs its own daemon, for example to start from a clean state in every job or to use a specific Docker version, add a docker:dind service and point DOCKER_HOST at the socket it creates:

build:
  tags: [your-dind-runner-tag]
  services:
    - docker:29-dind
  variables:
    DOCKER_HOST: unix:///runner/services/docker/docker.sock
  script:
    - docker build -t my-image .

GitLab’s usual setup with DOCKER_HOST: tcp://docker:2375 or tcp://docker:2376 does not work on these runners: the server’s socket is mounted into service containers too, so the service’s daemon cannot create its own socket and never starts. See Troubleshooting.

Concurrency

Concurrency is the number of jobs the runner runs at the same time (GitLab Runner’s global concurrent setting). When you select a product in the dashboard, it is set to twice the server’s vCPU count. Lower it for memory-hungry jobs.

Changes that recreate the server

Some settings are applied when the server is created. Changing them on an active runner makes Manage Runners delete the server and create a new one with the same IP addresses. Jobs running at that moment are interrupted.

Change Recreates an active runner’s server
Product yes
GitLab host yes
GitLab runner token yes
Concurrency yes
Executor yes
SSH keys yes
Cache, or the connection or sharing of the cache it uses yes
Metrics: Show in dashboard on or off yes
Metrics: the Send to connection, or none yes
The endpoint or headers of the connection it sends to yes
Name no
Labels GitLab runners: no, they are updated on the Hetzner server directly; DigitalOcean droplets get no labels. GitHub runners: yes, GitHub registers them
Hetzner or DigitalOcean token no
Location cannot be changed

Editing a paused runner never creates a server; the new settings apply when you resume it.

Costs

You pay two parties:

  • Your cloud provider bills you for the servers, at its own prices. The prices in the dashboard are the provider’s monthly net list prices, without VAT.

    • Hetzner bills your Hetzner account for the servers in your project for every started hour, up to the monthly price. While a runner is paused, it has no server. Hetzner may still charge for the IP addresses that are kept; see Hetzner’s pricing.
    • DigitalOcean bills the token’s account for the droplets per second, at least 60 seconds, up to the monthly price. While a runner is paused, it has no droplet, but its unassigned reserved IPv4 costs USD 5 a month. See Billing in DigitalOcean setup.

    Burst runners added by autoscaling are servers in your account too, billed the same way.

  • Manage Runners bills your plan. See Billing and plans and pricing.

Pausing runners when nobody needs them, by hand or with a schedule, is the main way to save server costs. The GitLab CI cost comparison compares these costs with GitLab’s hosted runners.