GitLab setup

Create a runner authentication token, choose tags, and connect runners to GitLab.com or a self-managed GitLab instance.

Manage Runners registers each server with GitLab using a runner authentication token. You create that token in GitLab, so you decide in GitLab which projects or groups can use the runner and which jobs it picks up.

Create a runner authentication token

Create the runner in GitLab first:

• Project runner: in the project, go to Settings > CI/CD, expand Runners and select New project runner.
• Group runner: in the group, go to Build > Runners and select New group runner.
• Instance runner (self-managed GitLab, administrators only): in the Admin area, go to CI/CD > Runners and select New instance runner.

In the form, set the tags and options described below and select Create runner. GitLab shows the token, which starts with glrt-. Paste it into the GitLab Runner Token field in Manage Runners.

GitLab’s documentation describes the steps in detail: Manage runners.

Manage Runners registers with the --token option of gitlab-runner register, which is the runner authentication token workflow. Registration tokens from GitLab’s deprecated registration workflow do not work.

Tags and untagged jobs

Manage Runners does not set tags. GitLab stores them with the runner you created:

• To send specific jobs to the runner, give it tags in GitLab, for example hetzner, and add the same tags to those jobs in .gitlab-ci.yml.
• To let it pick up jobs without tags, select Run untagged jobs in GitLab.

You can change tags and this option in GitLab at any time without touching the runner in Manage Runners.

GitLab.com and self-managed GitLab

Manage Runners works with GitLab.com and with self-managed GitLab instances. Enter the instance’s base URL in GitLab Host:

The server connects to this URL from the Hetzner location you chose, so a self-managed instance must be reachable from the internet, or at least from your runner’s IP addresses. Because the addresses stay the same while a runner is paused, you can allow them in your instance’s firewall. See IP addresses.

Manage Runners does not check the URL or the token when you save the runner. If either is wrong, registration fails on the server and the runner shows Invalid Gitlab Token. Select Fix to correct the token and the host.

When GitLab rejects the token

A runner shows Invalid Gitlab Token when gitlab-runner register did not succeed, for example because the token was mistyped, revoked, or belongs to another GitLab instance than the host you entered. The server keeps running in this state.

1. If needed, create a new runner in GitLab to get a new token.
2. In the dashboard, select Fix on the runner, paste the token and, if needed, correct the GitLab host.
3. Select Save. Manage Runners recreates the server, which registers again.

Removing a runner from GitLab

Deleting a runner in Manage Runners deletes its server, but it does not remove the runner from GitLab. GitLab shows it as offline. Delete it in GitLab under Settings > CI/CD > Runners when you no longer need it.