Zum Inhalt springen

~/CodeBlog.at

GitLab: Runner-Tokens zurücksetzen – 500er Fehler nach Upgrade oder Restore beheben

·3 Min. Lesezeit

Veröffentlicht
Überarbeitet

Was ist neu: Ursache erklärt, Diagnose mit gitlab:doctor:secrets, SQL an die aktuelle GitLab-Doku angepasst und Neuregistrierung mit dem neuen Runner-Workflow.

Kurz & knapp

Reagieren GitLab-Runner nicht mehr oder liefert /admin/runners einen 500er Fehler, kann GitLab meist die verschlüsselten Runner-Tokens nicht entschlüsseln – typischerweise wegen einer nicht passenden gitlab-secrets.json. Prüfen lässt sich das mit sudo gitlab-rake gitlab:doctor:secrets. Die Lösung: Tokens in der Datenbank zurücksetzen (sudo gitlab-rails dbconsole --database main) und die Runner mit einem neuen glrt--Token neu registrieren.

Getestet mit: GitLab CE 14.x (Reset damals durchgeführt), Befehle abgeglichen mit der Doku zu GitLab 18

Inhalt
  1. Die Ursache
  2. Diagnose
  3. Runner-Tokens zurücksetzen
  4. Runner neu registrieren
  5. Nützliches für die Fehlersuche

Auf meinem GitLab-Server (damals Version 14.x) hatte ich – soweit ich mich erinnere nach einem Upgrade – gleich zweimal das Problem, dass die GitLab-Runner nicht mehr reagierten. Im Admin-Bereich unter Runners gab es nur noch einen 500er Fehler. Die Runner einfach in der Oberfläche zu löschen, half nicht – sie mussten wirklich zurückgesetzt werden. Ein Hard Reset sozusagen.

Die Ursache

GitLab speichert Runner-Tokens verschlüsselt in der Datenbank. Der Schlüssel dafür liegt in /etc/gitlab/gitlab-secrets.json. Passen Datenbank und Secrets-Datei nicht zusammen – etwa nach einer Wiederherstellung, einer Migration auf einen neuen Server oder einem verunglückten Upgrade –, kann GitLab die Tokens nicht mehr lesen. Die Folge: ein 500er Fehler auf der Runner-Seite und Runner, die keine Jobs mehr abholen.

Diagnose

Ob GitLab Werte nicht entschlüsseln kann, prüft ein eigener Rake-Task:

sudo gitlab-rake gitlab:doctor:secrets

Er geht alle verschlüsselten Werte durch und meldet pro Bereich die Anzahl der Fehler (failures). Tauchen dort Runner, Projekte oder Namespaces auf, hilft der folgende Reset.

Runner-Tokens zurücksetzen

  1. In die Datenbank-Konsole wechseln:

    sudo gitlab-rails dbconsole --database main

    Bis GitLab 14.1 reichte sudo gitlab-rails dbconsole – ab 14.2 muss die Datenbank mit --database main angegeben werden.

  2. Alle Runner-Tokens leeren (laut aktueller GitLab-Dokumentation):

    -- Clear project tokens
UPDATE projects SET runners_token = null, runners_token_encrypted = null;

-- Clear group tokens
UPDATE namespaces SET runners_token = null, runners_token_encrypted = null;

-- Clear instance tokens
UPDATE application_settings SET runners_registration_token_encrypted = null;

-- Clear key used for JWT authentication
-- This may break the $CI_JWT_TOKEN job variable:
-- https://gitlab.com/gitlab-org/gitlab/-/issues/325965
UPDATE application_settings SET encrypted_ci_jwt_signing_key = null;

-- Clear runner tokens
UPDATE ci_runners SET token_encrypted = null;

  3. Konsole verlassen mit \q.

Runner neu registrieren

Seit GitLab 16 werden Runner nicht mehr mit einem gemeinsamen Registrierungs-Token angemeldet, sondern zuerst in GitLab angelegt. Dabei bekommt jeder Runner ein eigenes Authentifizierungs-Token mit dem Präfix glrt-.

Befehle für dich anpassen

Deine Eingaben werden in allen Befehlen dieser Seite eingesetzt und nur in deinem Browser gespeichert.

  1. In GitLab oben rechts Admin wählen, dann in der Seitenleiste CI/CD → Runners und Create instance runner.

  2. Betriebssystem und Tags festlegen und speichern – GitLab zeigt das Token (glrt-…) an.

  3. Auf dem Runner-Host registrieren:

    sudo gitlab-runner register \
  --url "https://gitlab.example.com/" \
  --token "glrt-…"

    Einstellungen wie Tags oder Beschreibung legst du jetzt im UI fest – gitlab-runner register übernimmt sie mit einem glrt--Token nicht mehr von der Kommandozeile.

Projekt- und Gruppen-Runner legst du analog in den CI/CD-Einstellungen des jeweiligen Projekts bzw. der Gruppe an.

Nützliches für die Fehlersuche

Tabellen anzeigen – in der Datenbank-Konsole (PostgreSQL):

\dt

Rails-Console öffnen – für Abfragen über die GitLab-Objekte statt direkt per SQL:

sudo gitlab-rails console

Häufige Fragen

Warum liefert /admin/runners einen 500er Fehler?

Meist kann GitLab verschlüsselte Werte wie Runner-Tokens nicht entschlüsseln, weil die gitlab-secrets.json nicht zur Datenbank passt – etwa nach einer Wiederherstellung oder Migration ohne die Secrets-Datei.

Wie prüfe ich, ob GitLab Werte nicht entschlüsseln kann?

Mit sudo gitlab-rake gitlab:doctor:secrets. Der Befehl prüft alle verschlüsselten Werte in der Datenbank und meldet Fehler pro Tabelle.

Was passiert mit meinen Runnern nach dem Reset?

Die bestehenden Runner können keine Jobs mehr abholen und müssen neu registriert werden. Seit GitLab 16 legt man Runner dafür im UI an und registriert sie mit einem Authentifizierungs-Token (Präfix glrt-).

Wie komme ich in die GitLab-Datenbank?

Bei der Omnibus-Installation mit sudo gitlab-rails dbconsole --database main. Die Angabe --database main ist seit GitLab 14.2 nötig.

Quellen & weiterführende Links

  1. Troubleshooting GitLab backups – When the secrets file is lost (öffnet in neuem Tab) – GitLab Docs
  2. Check Rake tasks (gitlab:doctor:secrets) (öffnet in neuem Tab) – GitLab Docs
  3. Migrating to the new runner registration workflow (öffnet in neuem Tab) – GitLab Docs
  4. Registering runners (öffnet in neuem Tab) – GitLab Docs
  5. Issue #57038: 500 Error on /admin/runners after migrating (öffnet in neuem Tab) – GitLab
  6. Rails console (öffnet in neuem Tab) – GitLab Docs

Geschrieben von

Christoph Schwob (öffnet in neuem Tab)

Ich bin Christoph Schwob, halbkreativer Entwickler aus Österreich und arbeite seit über 10 Jahren an und mit TYPO3. Hier sammle ich Lösungen, Code-Snippets und Notizen rund um TYPO3, macOS, Server, Homelab und alles andere.

Das könnte dich auch interessieren

Suche

Tippe einen Suchbegriff ein.