Wirklich letzter Blog
Anleitungen und Notizen zu Homelab, Linux und Netzwerk.
Forgejo Runner erstellen
Forgejo-Runner mit Docker Compose einrichten
Abschnitt betitelt „Forgejo-Runner mit Docker Compose einrichten“Nach einem Serverumzug wartet die Pipeline oft mit dem Hinweis „Waiting for a runner with the following label …“. Forgejo selbst läuft dann wieder, aber der Runner fehlt. Diese Anleitung zeigt, wie man den Forgejo-Runner mit Docker Compose neu aufsetzt. Ein einzelner Runner bedient dabei sowohl normale Container-Jobs als auch privilegierte Builds mit KVM.
Voraussetzungen
Abschnitt betitelt „Voraussetzungen“-
Ein Linux-Host mit Docker und Docker Compose. Unter Alpine:
Terminal-Fenster apk add docker docker-cli-composerc-update add docker defaultservice docker start -
Admin-Zugriff auf die Forgejo-Instanz
-
Für KVM-Jobs:
/dev/kvmmuss auf dem Host vorhanden sein. Auf einer VM heißt das, dass Nested Virtualization aktiviert sein muss.
1. Runner in Forgejo anlegen
Abschnitt betitelt „1. Runner in Forgejo anlegen“Unter Site Administration → Actions → Runners → Create new runner einen Runner anlegen und UUID und Token notieren.
Wichtig: Ein Runner, der in den Einstellungen eines einzelnen Repositorys angelegt wird, steht nur diesem Repository zur Verfügung. Soll er für alle Projekte arbeiten, legt man ihn auf Admin-Ebene an.
2. Konfiguration anlegen
Abschnitt betitelt „2. Konfiguration anlegen“mkdir -p /opt/docker/forgejo-runner/data/.cache/opt/docker/forgejo-runner/data/runner-config.yml:
log: level: info
server: connections: forgejo: url: https://git.example.com uuid: <UUID> token: <TOKEN>
runner: file: .runner capacity: 1 labels: - docker:docker://node:22-trixie - kvm:docker://debian:trixie
container: privileged: true
cache: enabled: true dir: /data/.cacheEin Label hat das Format <name>:docker://<standard-image>. Der Name muss zu runs-on: im Workflow passen. Das Image gilt nur für Jobs, die kein eigenes container.image angeben.
Achtung:
forgejo-runner generate-config > …überschreibt eine vorhandene Konfiguration ohne Rückfrage. Für die meisten Setups reicht die kurze Konfiguration oben. Alle anderen Werte haben sinnvolle Standards.
3. Docker Compose
Abschnitt betitelt „3. Docker Compose“/opt/docker/forgejo-runner/compose.yml:
services: runner: image: data.forgejo.org/forgejo/runner:13 restart: unless-stopped user: "0:0" working_dir: /data volumes: - /opt/docker/forgejo-runner/data:/data - /var/run/docker.sock:/var/run/docker.sock command: forgejo-runner daemon --config /data/runner-config.ymlAbsolute Pfade verhindern Überraschungen, wenn der Stack über eine Oberfläche wie Portainer oder Dockge verwaltet wird. Solche Tools lösen relative Pfade gegenüber ihrem eigenen Stack-Verzeichnis auf.
4. Starten und prüfen
Abschnitt betitelt „4. Starten und prüfen“cd /opt/docker/forgejo-runnerdocker compose up -ddocker compose logs -fIn Forgejo sollte der Runner nun als online und mit beiden Labels erscheinen. Nach jeder Änderung an der Konfiguration ist ein Neustart nötig:
docker compose restartTypische Fehler
Abschnitt betitelt „Typische Fehler“| Meldung | Ursache |
|---|---|
registration file not found |
Der Runner ist nicht registriert, server.connections fehlt. |
0 server connections configured |
server: ist doppelt vorhanden oder falsch eingerückt. |
cannot open config file |
Der Volume-Pfad stimmt nicht, die Datei liegt nicht unter /data. |
Waiting for a runner with label … |
Das Label fehlt, der Runner hängt am falschen Repository oder wurde nach einer Änderung nicht neu gestartet. |
Sicherheitshinweis
Abschnitt betitelt „Sicherheitshinweis“container.privileged: true gilt für alle Jobs dieses Runners. In Kombination mit dem gemounteten Docker-Socket haben Workflows damit faktisch Root-Zugriff auf den Host. Für eine private Instanz mit eigenen Repositories ist das vertretbar. Sobald fremde Pull Requests Workflows auslösen können, sollte man einen separaten, nicht privilegierten Runner einsetzen.