GitLab Runner einrichten

Plattform: Hetzner Cloud · Debian 13 (Trixie) · Shell Executor

Voraussetzung: Server ist vollständig eingerichtet und Docker läuft.

Vorbedingungen

SSH-Zugriff auf den Zielserver
Docker installiert und einsatzbereit (docker run --rm hello-world schlägt durch)
GitLab Runner Authentifizierungstoken — zu beziehen unter Settings → CI/CD → Runners → New project runner im GitLab-Projekt oder der Gruppe

1 — GitLab Runner installieren

Offizielles Repository einbinden und Paket installieren:

curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" \
  | bash

apt install -y gitlab-runner

Installation prüfen:

gitlab-runner --version

2 — Runner-Benutzer Docker-Zugriff erteilen

Die Installation legt den Systembenutzer gitlab-runner an. Er muss in der Gruppe docker sein, damit Shell-Executor-Jobs docker ohne Root aufrufen können.

usermod -aG docker gitlab-runner

Zugriff auf den Docker-Daemon prüfen:

sudo -u gitlab-runner docker info

Die Ausgabe muss Docker-Engine-Details ohne Fehler liefern. Bei "permission denied" den Dienst neu starten (Schritt 4) und erneut prüfen.

3 — Runner registrieren

Platzhalter durch GitLab-URL und Authentifizierungstoken ersetzen:

gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com" \
  --token "glrt-XXXXXXXXXXXXXXXXXXXX" \
  --executor "shell" \
  --description "hetzner-shell-runner" \
  --tag-list "shell,docker,hetzner"

Flag	Beschreibung
`--url`	Basis-URL der GitLab-Instanz (oder `https://gitlab.com` für GitLab SaaS)
`--token`	Authentifizierungstoken aus der GitLab-Oberfläche
`--executor`	Muss `shell` sein — Jobs laufen direkt auf dem Host und können `docker` aufrufen
`--description`	Anzeigename in der GitLab-Oberfläche
`--tag-list`	Kommagetrennte Tags zur Job-Zuweisung

Die Konfiguration wird nach /etc/gitlab-runner/config.toml geschrieben.

4 — Runner konfigurieren (optional)

Konfigurationsdatei öffnen und bei Bedarf Parallelität oder weitere Einstellungen anpassen:

nano /etc/gitlab-runner/config.toml

Relevante Parameter:

concurrent = 4          # maximale Anzahl paralleler Jobs

[[runners]]
  name = "hetzner-shell-runner"
  executor = "shell"
  [runners.cache]
    MaxUploadedArchiveSize = 0   # 0 = unbegrenzte Cache-Archivgröße

Nach Änderungen Dienst neu starten:

systemctl restart gitlab-runner

5 — Dienst aktivieren und abnehmen

Autostart sicherstellen und Dienststatus prüfen:

systemctl enable gitlab-runner
systemctl status gitlab-runner

Die Ausgabe muss active (running) zeigen. Anschließend Verbindung zu GitLab prüfen:

gitlab-runner verify

Erwartete Ausgabe:

Verifying runner... is valid    runner=XXXXXXXX

Der Runner muss unter Settings → CI/CD → Runners im GitLab-Projekt als online erscheinen.

6 — Feuerprobe

Testpipeline anlegen — .gitlab-ci.yml im GitLab-Projekt anlegen oder ergänzen:

test-runner:
  tags:
    - shell
  script:
    - echo "Runner ist einsatzbereit"
    - docker info
    - docker run --rm hello-world

Änderung pushen und unter CI/CD → Pipelines den erfolgreichen Abschluss bestätigen.

Troubleshooting

Runner nimmt keine Jobs an — Tags in .gitlab-ci.yml müssen mit der Tag-Liste des Runners übereinstimmen. Alternativ Run untagged jobs in den Runner-Einstellungen in GitLab aktivieren.

"permission denied" bei Docker-Befehlen — Gruppenmitgliedschaft mit id gitlab-runner prüfen — Ausgabe muss docker enthalten. Falls die Gruppe soeben hinzugefügt wurde, Dienst neu starten: systemctl restart gitlab-runner.

Runner erscheint offline in GitLab — Dienststatus prüfen (systemctl status gitlab-runner) und sicherstellen, dass ausgehender HTTPS-Traffic zur GitLab-Instanz nicht durch eine Firewall geblockt wird.

Jobs hängen oder laufen in Timeout — Job-Log in GitLab und Runner-Log auf dem Server prüfen: journalctl -u gitlab-runner -f.

Wartung

Runner aktualisieren: apt update && apt upgrade gitlab-runner
Logs einsehen: journalctl -u gitlab-runner --since "1 hour ago"
Runner abmelden: gitlab-runner unregister --token "glrt-XXX"
Konfigurationsdatei: /etc/gitlab-runner/config.toml

Ferrosoft Betriebshandbuch