idf-ci/docs/runner-setup.md

Gitea Actions Runner — Setup

Diese Anleitung beschreibt, wie der Gitea Actions Runner auf einem IDF-Server installiert und registriert wird. Der Runner ist der Dienst, der die Release-Workflows aus diesem Repo ausführt. Ohne laufenden Runner bleiben Tag-Pushes ohne Wirkung — die Runs hängen unendlich in der Queue.

Wichtig: Diese Anleitung ist die verbindliche SSOT für das Runner-Setup. Bei jedem Server-Wechsel wird sie von vorn abgearbeitet — es gibt keine versteckten Artefakte außerhalb von Git, nur die hier beschriebenen Schritte.

Was der Runner ist und was er nicht ist

Der Runner ist ein einzelnes ausführbares Binary (act_runner), das sich beim IDF-Gitea-Server anmeldet und Jobs aus der Queue abarbeitet. Er ist kein WordPress-, PHP- oder Plesk-Tool, sondern ein unabhängiger Dienst, der nebenher läuft. Technisch ist er vergleichbar mit einem Cron-Daemon, der auf Arbeit wartet.

Der Runner baut die Plugin-ZIPs und legt sie als Gitea-Release-Assets ab. Er verteilt nichts an Kunden — das ist Aufgabe des Master-Key-Plugins.

Voraussetzungen auf dem Server

• Linux (Debian/Ubuntu; der IDF-Plesk-Host reicht)
• Outbound-HTTPS zu git.ihre-ideenfabrik.de
• Standard-Tools verfügbar: bash, python3, zip, unzip, rsync, curl, jq, git Falls einzelne Tools fehlen: sudo apt install -y python3 zip unzip rsync curl jq git
• systemd (Standard bei Debian/Ubuntu)
• Root-Shell-Zugang

Installation

1. Binary herunterladen

Aktuelle stabile Version (beim Schreiben dieser Doku: v0.2.11) von https://gitea.com/gitea/act_runner/releases holen:

sudo mkdir -p /opt/act_runner
cd /opt/act_runner
sudo curl -L -o act_runner \
  https://gitea.com/gitea/act_runner/releases/download/v0.2.11/act_runner-0.2.11-linux-amd64
sudo chmod +x act_runner

Architektur-Variante: bei ARM-Servern linux-arm64 statt linux-amd64 wählen.

2. Konfigurationsdatei erzeugen

sudo ./act_runner generate-config | sudo tee config.yaml > /dev/null

Die Default-Konfiguration ist ok. Relevante Stellen, falls angepasst werden muss:

• runner.capacity — wie viele Jobs parallel laufen (Default: 1, für den Anfang ok)
• runner.labels — Labels, die der Runner kann. Hier setzen wir sie beim register explizit.

3. Registrierungstoken in Gitea holen

Organisation-scoped Runner (empfohlen, läuft für alle IDF-Repos):

1. In Gitea einloggen als Admin.
2. Navigation: Organization ideenfabrik → Settings → Actions → Runners.
3. Button „Create new Runner".
4. Registrierungstoken kopieren.

Alternativ: Instance-weit unter Site Administration → Actions → Runners (dann verfügbar für alle Organisationen).

4. Runner registrieren

sudo ./act_runner register \
  --config /opt/act_runner/config.yaml \
  --instance https://git.ihre-ideenfabrik.de \
  --token <TOKEN_AUS_SCHRITT_3> \
  --name idf-plesk-runner \
  --labels self-hosted:host,linux:host,x64:host \
  --no-interactive

Die Labels self-hosted, linux und x64 decken die Workflow-runs-on:-Kombinationen ab. Suffix :host = Jobs laufen direkt auf dem Host, ohne Docker. Damit sparen wir uns Docker als weitere Abhängigkeit.

Nach erfolgreicher Registrierung liegt eine Datei .runner im Arbeitsverzeichnis — die ist der Runner-State, nicht weiterkopieren oder committen.

5. systemd-Service anlegen

sudo tee /etc/systemd/system/act_runner.service > /dev/null <<'EOF'
[Unit]
Description=Gitea Actions Runner (IDF)
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/act_runner
ExecStart=/opt/act_runner/act_runner daemon --config /opt/act_runner/config.yaml
Restart=always
RestartSec=5
User=root
Group=root

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable act_runner
sudo systemctl start act_runner

6. Verifikation

sudo systemctl status act_runner

Erwartete Zeile: Active: active (running).

In Gitea prüfen:

1. Organization ideenfabrik → Settings → Actions → Runners.
2. Der neue Runner taucht mit Status Online auf.

7. Pilot-Test

Einen Plugin-Repo mit Caller-Workflow nehmen (z. B. idf-post-prefix), Tag v<X.Y.Z> pushen, unter Actions im Repo prüfen, ob der Run durchläuft. Bei Erfolg entsteht ein Gitea-Release mit ZIP-Asset.

Laufender Betrieb

• Logs: sudo journalctl -u act_runner -f (tail-folgen) oder journalctl -u act_runner --since '1 hour ago'.
• Runner-Update: neues act_runner-Binary herunterladen, ersetzen, sudo systemctl restart act_runner.
• Label-Änderung: act_runner register mit neuen Labels erneut ausführen (alten Runner in Gitea-UI vorher deaktivieren), Service neu starten.
• Deregistrierung: Runner in Gitea-UI löschen, .runner-Datei auf dem Server entfernen, Service stoppen.

Server-Wechsel — Checkliste

Wenn der IDF-Server gewechselt wird (neuer Plesk-Host o. ä.):

1. Diese Anleitung auf dem neuen Server von Schritt 1 an durchlaufen.
2. In Schritt 3 einen neuen Registrierungstoken erzeugen — alte Tokens nicht wiederverwenden.
3. Optional: den alten Runner in der Gitea-UI deaktivieren, damit er nicht doppelt zieht.
4. Nach Verifikation (Schritt 6 + 7): alte Server-Installation zurückbauen.

Damit ist das komplette Build-System portabel: die Bauanleitung lebt in diesem Repo (release-plugin.yml), der Runner wird pro Server neu aufgesetzt nach genau dieser Anleitung. Keine versteckten Scripts außerhalb von Git.

Troubleshooting

Runs hängen auf queued, Runner steht aber auf Online. Label-Mismatch. Der Workflow schreibt runs-on: self-hosted, der Runner muss dasselbe Label haben. act_runner register --labels … erneut, Service neu starten.

Runner zeigt offline nach systemd-Start. sudo journalctl -u act_runner --since '5 min ago' lesen. Häufige Ursachen: Token abgelaufen, DNS funktioniert nicht, git.ihre-ideenfabrik.de nicht erreichbar.

Pre-Flight-Check im Workflow schlägt fehl mit „Tool nicht gefunden". Das System-Paket fehlt auf dem Host. sudo apt install -y python3 zip unzip rsync curl jq git nachinstallieren.

Release-Anlage schlägt fehl mit 401/403. secrets: inherit im Caller-Workflow prüfen und sicherstellen, dass der Runner vom Repo aus GITEA_TOKEN bzw. github.token bekommt. Alternativ Access-Token als Secret im Repo/Org setzen.