Manage runners with the CLI
List, create, update, pause, resume, duplicate and delete runners, wait for them, and read their metrics from the terminal.
The examples use the active profile and organization. Add --profile or --org to choose others, and --output json for scripts. Commands that change runners need the scopes from Authentication. runner update and --wait also need runners:read, which the CLI’s login token always has.
List and inspect
manage-runners runner list
manage-runners runner get --id 812999368881481087
manage-runners runner get --name build-01
Runner IDs are long numbers; treat them as strings. Runners with a cache also show cacheId and cacheName. runner get --name needs an exact, unique name. The state field uses the API names: CREATING, CONFIGURING, READY (shown as Active in the dashboard), PAUSING, PAUSED, UNKNOWN and INVALID_GITLAB_TOKEN. See Runner states.
Find a server type and location
manage-runners product list
manage-runners product get --id hz-cpx31
manage-runners product locations --id hz-cpx31
product list shows Hetzner server types (hz-…) and, where offered, DigitalOcean droplet sizes (do-…, with provider DigitalOcean). product locations shows where the provider offers the product and its monthly net price in each location. Use the location code, for example fsn1 or fra1, with runner create.
To see the SSH keys of your Hetzner project, pass the Hetzner token on standard input or through an environment variable:
manage-runners provider hetzner ssh-keys --token-env HCLOUD_TOKEN
With a saved token, pass --hetzner-token <id> instead. For DigitalOcean, use provider digitalocean ssh-keys with a DigitalOcean token. For an existing runner, runner ssh-keys --id <id> lists the keys available with the runner’s stored token.
Create a runner
The CLI reads the GitLab runner token and the cloud provider’s token from environment variables you name, so they never appear on the command line:
export GLRT_TOKEN HCLOUD_TOKEN # set them from your secret manager
manage-runners runner create \
--name build-01 \
--product-id hz-cpx31 \
--location fsn1 \
--executor docker \
--concurrency 8 \
--gitlab-host https://gitlab.com/ \
--runner-token-env GLRT_TOKEN \
--hetzner-token-env HCLOUD_TOKEN \
--ssh-key-id 1234567 \
--label role=ci-runner \
--dashboard on \
--send-to OpenObserve \
--wait
| Flag | Required | Description |
|---|---|---|
--name |
no | Letters, numbers, spaces and dashes; without it the runner gets a name such as swift-falcon, shown as name in the result |
--product-id |
yes | From product list |
--location |
yes | From product locations |
--executor |
yes | docker, dind or shell |
--concurrency |
yes | At least 1 |
--gitlab-host |
yes | Base URL of your GitLab instance |
--runner-token-env |
yes | Name of the variable holding the glrt- token |
--provider |
no | hetzner (default) or digitalocean; see Runners on DigitalOcean |
--hetzner-token-env |
yes, or --provider-token-env or --hetzner-token |
Name of the variable holding the Hetzner token; it is saved to your organization, or matched with a saved token |
--hetzner-token |
no | ID of a saved Hetzner token instead of --hetzner-token-env |
--provider-token-env |
for DigitalOcean, or --digitalocean-connection |
Name of the variable holding the cloud provider’s token; for Hetzner, the same as --hetzner-token-env |
--digitalocean-connection |
no | ID of a DigitalOcean connection instead of a token, with --provider digitalocean; see provider digitalocean connections |
--ssh-key-id |
no | SSH key ID of the Hetzner project or DigitalOcean account, repeatable |
--label |
no | Hetzner label, repeatable; not put on DigitalOcean droplets |
--dashboard on|off |
no | Metrics: show in dashboard; needs an active plan to turn on |
--send-to |
no | Metrics: send to this connection, an ID or name from metrics list; needs an active plan |
--cache |
no | Cache ID or name from cache list |
--wait |
no | Wait until the runner reaches a final state |
--yes |
no | Confirm creating paid resources without a prompt |
runner create creates a paid Hetzner server or DigitalOcean droplet, so it asks create runner build-01 and potentially create paid resources? [y/N] (without --name: create runner with a generated name …). Pass --yes in scripts. Without a terminal and without --yes, it fails.
Each create request carries an idempotency key. The CLI generates a new one per invocation; pass your own with --idempotency-key (16 to 128 letters, digits, ., _ or -) to make a script’s retry safe. For the same user, organization, route, key and request, the API returns the first result until 24 hours after the first attempt; after that, the same request creates another runner. A different request with the same key, or a retry while the first attempt has not completed, is rejected as a conflict. Check runner list before retrying an old create. See Idempotency and unknown outcomes.
Saved Hetzner tokens
Your organization keeps its Hetzner tokens as named, saved tokens, which runners and autoscaling use instead of their own copy (see Saved Hetzner tokens). provider hetzner tokens lists them with their ID, name and the runners and policies that use them, never their values, and --hetzner-token <id> takes the place of --hetzner-token-env in runner create, runner update, runner autoscaling set and provider hetzner ssh-keys:
manage-runners provider hetzner tokens
manage-runners runner create --name build-02 --product-id hz-cpx31 --location fsn1 --executor docker \
--concurrency 8 --gitlab-host https://gitlab.com/ --runner-token-env GLRT_TOKEN --hetzner-token 123456789 --wait
runner update --hetzner-token <id> switches a runner to another saved token, and only to one of the same Hetzner project (HETZNER_PROJECT_MISMATCH otherwise). Saving, replacing and deleting saved tokens is done in the dashboard; a request that uses a saved token while it is replaced fails with HETZNER_TOKEN_REPLACED; a create then created nothing, and after an update runner get shows what was stored. Retry it.
Runners on DigitalOcean
Runners run on Hetzner unless runner create gets --provider digitalocean. Such a runner takes a DigitalOcean product (do-…), a DigitalOcean region such as fra1 as --location, and the token from the variable named by --provider-token-env; --hetzner-token-env is refused with --provider digitalocean. The token needs the custom scopes listed in DigitalOcean setup.
export GLRT_TOKEN DIGITALOCEAN_TOKEN # set them from your secret manager
manage-runners provider digitalocean ssh-keys --token-env DIGITALOCEAN_TOKEN
manage-runners runner create --provider digitalocean --name do-builder \
--product-id do-s-2vcpu-4gb --location fra1 --executor docker --concurrency 2 \
--gitlab-host https://gitlab.com/ --runner-token-env GLRT_TOKEN \
--provider-token-env DIGITALOCEAN_TOKEN --wait
Instead of a token, a runner can use a DigitalOcean team your organization connected in the dashboard. provider digitalocean connections lists the connections with their ID, team and status, and --digitalocean-connection <id> takes the place of --provider-token-env in runner create --provider digitalocean, runner update, runner autoscaling set and provider digitalocean ssh-keys. runner update --digitalocean-connection <id> switches a runner between a token and a connection of the same team. Connecting a team needs the browser.
runner get and runner list show provider (digitalocean) for runners that are not on Hetzner; Hetzner runners have no provider field. runner update --provider-token-env NAME replaces a runner’s token; the provider and location of a runner cannot change. DigitalOcean’s refusals have their own error codes, for example INVALID_PROVIDER_TOKEN or PROVIDER_VM_CREATION_ERROR at the droplet or reserved IP limit, with DigitalOcean’s message in details.detail. DigitalOcean support needs CLI 1.9.0 or later, DigitalOcean connections 1.10.0 or later.
Wait for a runner
--wait on create, update, pause, resume and duplicate waits until the runner reaches READY, PAUSED, UNKNOWN or INVALID_GITLAB_TOKEN, for at most --timeout (default 10 minutes). Check the returned state: reaching UNKNOWN or INVALID_GITLAB_TOKEN ends the wait too.
To wait later or for a specific state:
manage-runners runner wait --id 812999368881481087 --state READY --timeout 15m
manage-runners runner watch --id 812999368881481087
If the wait times out, the command exits with code 7 (TIMEOUT). If it fails for another reason, for example a token without runners:read, it exits with that error. In both cases the change itself was accepted and is not undone; check the runner with runner get.
Update a runner
manage-runners runner update --id 812999368881481087 --name build-02 --label role=ci-runner
manage-runners runner update --id 812999368881481087 --concurrency 4 --yes --wait
Flags you leave out keep their current values. --label and --ssh-key-id replace the whole list. --cache selects another cache and --no-cache removes it.
--product-id,--gitlab-host,--runner-token-env,--concurrency,--executor,--ssh-key-id,--cache,--no-cache,--dashboard,--send-toand--no-send-torecreate an active runner’s server and interrupt its jobs. The CLI asks for confirmation, or needs--yes.--labeldoes too on a GitHub runner, which registers its labels with GitHub.--name,--hetzner-token-env,--provider-token-envand, on a GitLab runner,--labelalone never recreate the server. See Changes that recreate the server.
The location and the provider cannot be changed.
Pause, resume and duplicate
manage-runners runner pause --id 812999368881481087 --yes
manage-runners runner resume --id 812999368881481087 --yes --wait
manage-runners runner duplicate --id 812999368881481087 --yes
pause deletes the server and keeps the IP addresses. The runner first lets its running jobs finish: pause answers with the state PAUSING, the runner takes no new jobs, and the server is deleted once the jobs have finished, after at most one hour. A busy GitHub runner can still get jobs that ask only for GitHub’s default labels until its job ends; see Pause and resume. --force deletes the server at once, interrupting running jobs, and also ends a pause in progress. With --wait, pass a --timeout of more than an hour to wait for a full drain. resume and duplicate create servers and may cost money. All three ask for confirmation unless you pass --yes.
Delete a runner
Deleting needs the runners:delete scope and the runner ID twice, as --id and --confirm:
manage-runners runner delete --id 812999368881481087 --confirm 812999368881481087 --yes
Interactively, the CLI asks you to confirm and to type the ID. Delete removes the server, the IP addresses and the runner’s schedule. It does not remove the runner from GitLab.
If deletion cannot be confirmed with the provider, the runner is kept and the command fails. Run it again later. A paused DigitalOcean runner whose reserved IPv4 DigitalOcean has not released yet is kept with PROVIDER_IP_DELETION_PENDING; run the delete again in a few minutes.
Forget an Unknown runner
runner forget only works on a runner in the UNKNOWN state. It removes the record from Manage Runners and leaves any server and IP addresses at the provider untouched. It needs the runners:forget scope and the same confirmation as delete:
manage-runners runner forget --id 812999368881481087 --confirm 812999368881481087 --yes
Never use forget instead of delete. Try recovering the runner first, and clean up the server and its IP addresses at the provider yourself afterwards.
Read metrics
manage-runners runner metrics
manage-runners runner metrics --name build-01 --range 7d --output json
Without --id or --name, runner metrics covers every active runner that shows metrics in the dashboard (--dashboard on). --range accepts 1h, 24h (default), 7d, 30d and 90d. Human output shows the latest CPU, RAM, swap (only if the server has swap), running jobs out of the concurrency (only if the server reports them) and disk usage and a summary of the history; JSON includes the full history.
latestis empty until the first sample arrives, andstalemarks samples older than three minutes.- A runner that is not monitored or not active fails with
NOT_MONITORED(exit code 5). - Without an active plan, the command fails with
SUBSCRIPTION_REQUIRED(exit code 4). - If the history is shorter than the range, a
RANGE_EXCEEDS_HISTORYwarning lists the available ranges.
Metrics connections
A runner can send its metrics to an OTLP/HTTP endpoint of your organization, independently of showing them in the dashboard. The organization’s named connections are managed with the metrics commands, which select a connection by --id or --name like the cache commands. Reading them needs runners:read; changes need runners:write, and creating or changing a connection also needs an active plan:
manage-runners metrics list
export OTLP_AUTH="Basic $(printf '%s' 'you@example.com:ingest-token' | base64 | tr -d '\n')"
manage-runners metrics create --name OpenObserve \
--endpoint https://api.openobserve.ai/api/acme \
--header-env Authorization=OTLP_AUTH
manage-runners runner update --id 812999368881481087 --send-to OpenObserve --yes
| Command | Description |
|---|---|
metrics list |
All connections with their endpoint, header names and usedBy, the runners that use them |
metrics get --id <id> or --name <name> |
One connection |
metrics create --name <name> --endpoint <url> |
A new connection, with optional header flags |
metrics update --id <id> or --name <name> |
Change the endpoint or headers, or rename it with --new-name |
metrics delete --id <id> or --name <name> |
Delete it and stop its runners sending to it; needs --yes without a terminal |
--endpointis the base URL; the collector appends/v1/metrics.- Header values never go on the command line:
--header-env NAME=VARreads one from an environment variable,--header-stdin NAMEfrom stdin, and--header NAMEkeeps the stored value or asks for it in a terminal. - On
metrics update, the headers you give replace the stored ones. Without header flags they are kept;--no-headersremoves them. - Changing the endpoint or headers, and
metrics delete, recreates the servers of the active runners that use the connection; renaming it does not. Without--yesthe command fails withMETRICS_CONNECTION_RECREATE_REQUIREDand lists them, or asks in a terminal. Runners markedrecreate: falseare Unknown and keep the previous settings until you edit or recreate them.RUNNER_LOCKEDlists runners that are busy; try again later. --send-to <id|name>onrunner createorrunner updateselects the connection to send to; a name needsrunners:read.--no-send-tosends to none. An unknown connection fails withINVALID_METRICS_CONNECTION(exit code 7).runner getandrunner listshowmetricsConnectionId,metricsConnectionNameandmetricsStatus, the last result, for exampleokorauth, with the time it was reported.
If a change has an unknown outcome
If the connection fails while a change is in progress, the CLI exits with code 10 (UNKNOWN_OUTCOME). The change may or may not have happened. Check the runner with runner list or runner get before you try again; never retry blindly.