Manage Runners
Documentation menu

Runners

Create, edit, duplicate, pause, resume, delete and remove runners in the dashboard.

The Dashboard lists the runners of the selected organization as cards. Each card shows the runner’s state, chip, vCPUs, RAM, disk, concurrency, executor, IPv4 and IPv6 addresses (select one to copy it), location, the provider and its monthly price. Use the filters above the list to narrow it down by status, executor or location, or search by name.

The dashboard with an active and a paused runner

Owners and editors can change runners. Viewers see the list without actions and a View only badge. The dashboard needs an active plan; without one it opens Billing.

Create a runner

Select Create Runner, fill in the form and select Create. The quick start explains every field. Some rules:

  • Name (optional): letters, numbers, spaces and dashes only. Other characters are removed as you type. Leave it blank and the runner gets a name such as swift-falcon that isn’t already used in your organization.
  • Cloud provider: Hetzner or DigitalOcean. Changing it clears the product, location, token and SSH keys. A runner’s provider cannot change later.
  • Product and location: choose the product first; the location list then shows where the provider offers it and at what price. Locations where it is unavailable are disabled.
  • Concurrency: at least 1. Selecting a product sets it to twice the vCPU count.
  • Tokens: the GitLab runner authentication token and, for Hetzner, one of your organization’s saved Hetzner tokens or a new token with read and write access, which is saved for the next runners; for DigitalOcean, a DigitalOcean API token with the listed custom scopes or a connected team.
  • Cache (optional): an S3 bucket for the GitLab CI cache, or None. See Caches.
  • Metrics: Show in dashboard is on by default when your organization’s plan is active; Send to is None by default, or one of your organization’s connections to an OpenTelemetry endpoint. See Metrics.

The runner appears as Creating, then Configuring, then Active. The dashboard refreshes the list while any runner is changing state.

Edit a runner

Select Edit on the card, change the settings and select Save changes.

  • Location cannot be changed, because that would change the runner’s IP addresses. To move a runner, create a new one in the other location.
  • Product offers only server types of the runner’s provider that are available in its location.
  • Tokens show as ********. Leave a token field empty to keep the stored token. A Hetzner runner shows its saved token; choosing another one, or entering a new one, only works with a token of the runner’s Hetzner project.

Changing the product, GitLab host, GitLab token, concurrency, executor, SSH keys, cache or metrics settings of an active runner deletes its server and creates a new one. Running jobs are interrupted. Changing the name or provider token does not, nor do labels of a GitLab runner; a GitHub runner’s labels do. See Changes that recreate the server.

Duplicate a runner

Select Duplicate to create a copy with the same product, location, executor, concurrency, GitLab host and token, provider token (the same saved Hetzner token), SSH keys, labels, cache and metrics settings. The copy’s name gets a number, for example build-01 2. It starts as a new runner and creates its own server and IP addresses.

You can duplicate active and paused runners. Duplicate is disabled when the provider no longer offers the runner’s server type in its location.

Pause and resume

Pause deletes the runner’s server. The runner keeps its configuration and its IPv4 and IPv6 addresses, and the provider stops billing for the server. On DigitalOcean, the kept reserved IPv4 costs USD 5 a month while the runner is paused.

Pause asks how:

  • Pause after running jobs lets the jobs that are running finish. The runner is Pausing: it takes no new jobs, and the server is deleted once the running jobs have finished, at the latest one hour after you paused it. The provider bills the server until then.
  • Pause now deletes the server at once and interrupts the running jobs.

While a runner is Pausing, Pause now ends the wait and deletes the server at once.

A pausing GitHub runner is removed from GitHub as soon as it has no running job. While one of its instances is still running a job, it no longer gets jobs that ask for your own labels, but GitHub can still give it jobs that ask only for the default labels self-hosted, the operating system or the architecture, until that job has finished. Give your workflows one of the runner’s own labels in runs-on to avoid that.

GitLab runners created before Manage Runners let jobs finish stop their jobs right away when they are paused. Edit a runner in a way that recreates its server, or pause and resume it, to give it the new behaviour.

Resume creates a new server with the same configuration and addresses. The runner goes through Creating and Configuring again before it is Active. Because the server is new, nothing from its previous disk remains.

If the provider no longer offers the server type in the runner’s location, Resume is disabled, and the card warns you before you pause a runner that could not be resumed. If the provider cannot create the server when you resume, for example because of capacity problems on Hetzner or an account limit on DigitalOcean, the runner stays paused and the card shows the error. Try again later, or edit the runner to use another server type.

To pause and resume on a timetable, use a schedule.

Delete a runner

Select Delete, then select it again to confirm. Manage Runners deletes the server, the runner’s IP addresses and its schedule.

If the provider does not confirm that the server was deleted, the runner is kept and the card shows an error, so you can try again. A server that no longer exists at the provider counts as deleted. On DigitalOcean, a reserved IPv4 can take some minutes to be released after its droplet is gone; see What Manage Runners creates.

Deleting a runner does not remove it from GitLab. Delete it in GitLab when you no longer need it.

Remove an Unknown runner

A runner in the Unknown state cannot be deleted normally, because Manage Runners does not know whether its server still exists. Selecting Delete on it opens Delete Unknown Runner, which only removes the runner from the dashboard:

If you delete an unknown runner, the ip and hetzner server will not be deleted.

For a DigitalOcean runner, the dialog names its droplet and reserved IPs instead. After you confirm, check the Hetzner Console or the DigitalOcean control panel and delete the server and its IP addresses there if they still exist. Before you remove an Unknown runner, see whether editing it can recover it.

When actions are unavailable

Action Unavailable while the runner is
Duplicate, Resume Creating, Unknown, or Pausing
Pause Creating or Unknown; while Pausing it is Pause now
Delete Creating
Edit Invalid Gitlab Token (use Fix instead)

Only one lifecycle action runs on a runner at a time. If you start another one, it fails with a message that the runner is locked. Wait until the first action has finished.