Manage Runners Logo
Manage Runners
Documentation menu
View as Markdown

Quick start

Create an account, connect Hetzner and GitLab, start your first runner and run a job on it.

This guide takes you from a new account to a CI/CD job running on your own runner. It takes about 15 minutes, most of it waiting for the server to start.

You need:

  • A Hetzner Cloud account.
  • A GitLab project on GitLab.com or on your own GitLab instance, where you have the Maintainer or Owner role.
  • An authenticator app for two-factor authentication.

1. Create your account

  1. Open https://app.managerunners.com/register.
  2. Enter your email address, given name, family name and a password. The password needs at least 8 characters with an uppercase letter, a lowercase letter, a number and a symbol.
  3. Select Create account.
  4. Scan the QR code with your authenticator app, enter the 6-digit code and select Verify & Continue.

Two-factor authentication is always on. You enter a code from your authenticator app every time you sign in.

2. Choose a plan

The dashboard opens Billing until your organization has an active plan. Choose a plan and complete the checkout. Every plan includes unlimited runners; schedules need Pro or Enterprise. See Billing and plans and pricing.

3. Create a Hetzner API token

Manage Runners creates and deletes servers in your Hetzner project, so it needs a token with read and write access.

  1. In the Hetzner Cloud Console, create a project for your runners, for example gitlab-runners. A separate project keeps runner servers apart from your other infrastructure.
  2. Open the project, go to Security > API tokens and generate a token with Read & Write permission.
  3. Copy the token. Hetzner shows it only once.

Optional: to log in to the runner servers over SSH, add your public key under Security > SSH keys in the same project. You can select it when you create the runner.

See Hetzner setup for details.

4. Create a GitLab runner and copy its token

GitLab issues a runner authentication token (it starts with glrt-) when you create a runner in the GitLab UI. Manage Runners uses this token. The older registration tokens are not used.

  1. In your GitLab project, go to Settings > CI/CD and expand Runners.
  2. Select New project runner.
  3. Add the tags your jobs will use, for example hetzner, or select Run untagged jobs.
  4. Select Create runner and copy the runner authentication token.

You can also create group or instance runners. See GitLab setup.

5. Create the runner

In the dashboard, select Create Runner and fill in the form:

Field What to enter
Name A name with letters, numbers, spaces and dashes, for example build-01.
Product The Hetzner server type. Each option shows the CPU architecture, vCPUs, RAM and disk.
Location The Hetzner location. Each option shows Hetzner’s monthly net list price.
Executor docker for most projects. See executors.
Concurrency How many jobs run at once. Selecting a product sets it to twice the vCPU count.
GitLab Host https://gitlab.com/, or the base URL of your self-managed GitLab instance.
GitLab Runner Token The glrt- token from step 4.
Hetzner Auth Token The token from step 3. The form checks it and loads the project’s SSH keys.
Hetzner SSH Keys Optional keys for root access to the server.
Labels Optional labels that are attached to the Hetzner server.
Resource monitoring Optional CPU, RAM and disk charts. Requires an active plan.

The Create Runner form filled in with a Docker runner on a CPX31 server in Falkenstein

Select Create. The dashboard shows the runner as Creating while Hetzner starts the server, then Configuring while it installs GitLab Runner. After a few minutes it changes to Active.

The dashboard with an active and a paused runner

If the runner shows Invalid Gitlab Token instead, GitLab rejected the token. Select Fix on the runner and paste a new one.

6. Run a job

In GitLab, the runner now appears under Settings > CI/CD > Runners as online. Add a job to .gitlab-ci.yml that uses its tag:

hello:
  image: alpine:latest
  tags:
    - hetzner
  script:
    - echo "Running on my own Hetzner runner"

Commit the file. GitLab assigns the job to your runner. If you selected Run untagged jobs, the tags section is not needed.

7. Pause it when you don’t need it

A runner costs Hetzner server time while it is active. Select Pause on the runner card to delete the server. The runner keeps its configuration and its IP addresses, so firewall rules and allow lists that mention them keep working. Select Resume to create a fresh server with the same settings.

To pause and resume automatically, for example outside working hours, set up a schedule. Schedules need a Pro or Enterprise plan.

Prefer the command line?

The same steps with the manage-runners CLI, after the account and plan exist:

manage-runners auth login --scope runners:write
manage-runners product list
manage-runners product locations --id hz-cpx31

export HCLOUD_TOKEN GLRT_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 --wait

See Manage runners with the CLI for every option.

Next steps