Zum Inhalt springen
Wirklich letzter Blog

Wirklich letzter Blog

Anleitungen und Notizen zu Homelab, Linux und Netzwerk.

Neueste Beiträge

Forgejo Runner erstellen

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.

  • Ein Linux-Host mit Docker und Docker Compose. Unter Alpine:

    Terminal-Fenster
    apk add docker docker-cli-compose
    rc-update add docker default
    service docker start
  • Admin-Zugriff auf die Forgejo-Instanz

  • Für KVM-Jobs: /dev/kvm muss auf dem Host vorhanden sein. Auf einer VM heißt das, dass Nested Virtualization aktiviert sein muss.

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.

Terminal-Fenster
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/.cache

Ein 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.

/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.yml

Absolute 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.

Terminal-Fenster
cd /opt/docker/forgejo-runner
docker compose up -d
docker compose logs -f

In Forgejo sollte der Runner nun als online und mit beiden Labels erscheinen. Nach jeder Änderung an der Konfiguration ist ein Neustart nötig:

Terminal-Fenster
docker compose restart
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.

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.