Hetzner setup
Create the Hetzner Cloud API token, save it for your organization, and learn what Manage Runners creates in your project and how to use SSH keys, labels and firewalls.
Your runners are servers in your own Hetzner Cloud project. Manage Runners manages them through the Hetzner Cloud API with a token you provide. Hetzner is the default provider; for runners on DigitalOcean, see DigitalOcean setup.
Create a project and an API token
- In the Hetzner Cloud Console, create a project for your runners. The dashboard recommends a separate project that only contains your runners, so the token cannot affect other servers.
- In the project, go to Security > API tokens and generate a token with Read & Write permission. Manage Runners creates and deletes servers and changes IP addresses, which a read-only token cannot do.
- Copy the token and save it under Organization settings > Hetzner tokens > Add token, or paste it when you create a runner with Enter a new token.
Manage Runners checks a token with Hetzner by listing the project’s SSH keys. That check only reads, so it also accepts a read-only token. A read-only token fails later, when the server is created, and the runner becomes Unknown.
Saved Hetzner tokens
Your organization keeps its Hetzner tokens as saved tokens, each with a name, for example Production project. Runners, their duplicates and burst runners, and autoscaling templates use a saved token instead of their own copy. You enter a token once, every runner that should use it picks it by name, and replacing it once updates all of them. Different runners can still use different saved tokens, and so different Hetzner projects.
- Create runner and Edit runner with Hetzner selected show Hetzner API token with your saved tokens, by default the one used most recently. Choose Enter a new token to paste another one and, optionally, give it a name. It is checked with Hetzner and saved to your organization; without a name it is named after the runner, for example build-01 token. A token your organization saved already is not saved twice: the form says which saved token the runner will use.
- The SSH keys come from the project of the chosen token.
- The autoscaling page offers the same choice for burst runners, see Autoscaling.
- Organization settings > Hetzner tokens lists the saved tokens, who saved them and the runners and autoscaling policies that use each. Owners and editors add, rename, replace and delete them; viewers see the list. A token is never shown again after it is saved.
Saved tokens are stored encrypted for your organization. The API, the CLI and AI assistants show their names and IDs, never their values.
Replace a saved token
To use a new token, for example after revoking the old one in the Hetzner Console, select Replace next to the saved token and enter the new one. It must belong to the same Hetzner project: Manage Runners checks that the new token sees the server of every active runner and the primary IP addresses of every paused runner that use the saved token, and refuses it with the names of the runners it cannot reach otherwise. Replacing a token does not recreate any server. While a runner that uses the saved token is being created, started, paused or changed, the replacement is refused with its name; try again once it is ready.
Runners that became Unknown because Hetzner refused the old token are checked again right after the replacement and become Active or Paused, without editing each of them. Edit runner on such a runner points to Replace the saved token and shows how many runners and policies use it.
Delete a saved token
A saved token that runners or autoscaling policies still use cannot be deleted: the dashboard names them. Switch them to another token, or delete them, first. A runner you deleted keeps the token until its server is gone and is listed as being deleted meanwhile. Deleting a saved token does not revoke it at Hetzner; delete it in the Hetzner Console as well if you no longer need it.
Existing runners
Before saved tokens, each runner kept its own copy of the token. When saved tokens were introduced, Manage Runners grouped these copies automatically: per organization, every distinct token became one saved token, named after the alphabetically first runner that used it, for example build-01 token, and all runners, burst runners and autoscaling templates with that token now use it. Rename the saved tokens to something meaningful in Organization settings > Hetzner tokens.
What Manage Runners creates
In your project, Manage Runners creates:
- one server per active runner, named after the runner and its ID, for example
build-01-812999368881481087; - a primary IPv4 and a primary IPv6 address for each server. They stay in your project while the runner is paused and are deleted with the runner.
It does not create firewalls, networks, volumes or SSH keys.
Do not delete or change runner servers in the Hetzner Console. Manage Runners does not watch the project for such changes, and the runner can end up in a state that does not match reality. Pause, resume and delete runners from the dashboard or the CLI instead.
SSH keys
Manage Runners does not create SSH keys. To log in to a runner’s server:
- Add your public key to the project under Security > SSH keys in the Hetzner Console.
- When you create or edit the runner, select the key under Hetzner SSH Keys. The list shows the keys of the project that the Hetzner token belongs to.
Selected keys are added to the server’s root account. Password login is disabled. Changing the selected keys of an active runner recreates its server.
Labels and firewalls
Labels you add to a runner become Hetzner server labels. A label written as key=value becomes the Hetzner label key with the value value. A label without = becomes a label with an empty value. Manage Runners also gives every server it creates, and its primary IP addresses, the label managerunners-runner with the runner’s id, so it can find them again; a label of yours with that key is replaced.
Hetzner firewalls can apply to all servers with a given label. To protect your runners with a firewall:
- Create a firewall in the Hetzner Console with the rules you want.
- Under Apply to, choose Label selector and enter a label, for example
role=ci-runner. - Add the same label to your runners.
GitLab Runner only makes outgoing connections to your GitLab instance, so a runner needs no incoming rules for GitLab. Keep SSH open only if you log in to the servers. Changing labels never recreates a server.
Changing the token
To give all runners of a saved token a new token, replace the saved token. To move one runner to another token, edit it and choose another saved token or Enter a new token; the token must belong to the project the runner’s server and primary IP addresses are in. Changing only the token does not recreate the server. If the runner was Unknown because its token stopped working, saving makes Manage Runners check the project again. See Troubleshooting.