Forgejo Runner 13.1.0 öffnet die Job-Ausführung für externe Plugins. Für den Selbstbetrieb bedeutet das mehr Auswahl bei den Execution Engines, allerdings mit einem Alpha-Protokoll und einer kleinen Breaking Change bei Terminal-Ausgaben.
Mehr als Docker und LXC
Forgejo Runner konnte Jobs bisher in Docker oder Podman, in LXC-Containern oder direkt auf dem Host ausführen. Mit Version 13.1.0 kommt eine experimentelle Plugin Capability hinzu. Externe Anwendungen können damit eigene Execution Engines bereitstellen, etwa für Firecracker microVMs, Kubernetes Pods, QEMU oder libvirt VMs und systemd-nspawn Container.
Der Forgejo-Entwicklung fehlen laut Release-Ankündigung die Kapazitäten, all diese Varianten selbst zu entwickeln und dauerhaft zu supporten. Das Plugin-Modell verlagert diese Arbeit an separate Projekte. Forgejo Runner übernimmt dabei die Kommunikation und den Ablauf eines Jobs, während das Plugin die konkrete Umgebung erstellt und verwaltet.
Die Verbindung läuft über gRPC. Ein Plugin stellt den Service plugin.v1alpha bereit, typischerweise über einen lokalen TCP-Port oder einen UNIX socket. Zusätzlich muss der standardisierte grpc.health.v1 Service implementiert werden. Die API ist ausdrücklich als Alpha eingestuft und besitzt derzeit keine Stabilitätsgarantie.
Konfiguration über Labels
Ein Plugin wird in der Konfigurationsdatei von Forgejo Runner unter plugins eingetragen. Dort stehen der Name, die Adresse und optionale Parameter. Möglich sind beispielsweise 127.0.0.1:50051 oder ein Socket wie unix:///run/my-plugin.sock.
Für Workflows wird anschließend ein Label definiert. Ein Label wie my-plugin-a:my-plugin://some-parameter verbindet den sichtbaren runs-on Wert mit dem konfigurierten Plugin. Ein Job mit runs-on: my-plugin-a verwendet dann diese Execution Engine. Der Parameter kann an das Plugin übergeben werden und lässt sich bei Bedarf über jobs.<job_id>.container.image überschreiben.
Beim Start fragt Forgejo Runner zunächst die Fähigkeiten des Plugins ab. Danach folgen RPC-Aufrufe zum Erstellen und Starten der Umgebung. Für jeden Workflow-Schritt werden Dateien hineinkopiert, Befehle ausgeführt und Ergebnisdateien wieder ausgelesen. Am Ende entfernt der Runner die Umgebung über einen weiteren RPC-Aufruf. Das betrifft auch Action-Code, etwa bei actions/checkout@v4.
Für den Betrieb entsteht damit eine zusätzliche Komponente mit eigener Überwachung, eigener Fehlerbehandlung und eigenem Update-Zyklus. Das Plugin muss verfügbar sein, bevor Jobs starten. Bei einem lokalen Socket sind Berechtigungen und der Lebenszyklus des Daemons zu prüfen. Bei einer Netzwerkadresse kommen zusätzlich Erreichbarkeit und Absicherung der Verbindung hinzu.
Alpha bleibt Alpha
Forgejo Runner 13.1.0 ist laut Release Notes der erste Release mit diesem Plugin Engine. Die Beispielimplementierungen testplugin in Go und runner-systemd-nspawn in Rust dienen der Validierung und als Referenz. Für Production Usage sind sie ausdrücklich nicht geeignet.
Für produktive Self-Hosting-Setups empfiehlt sich deshalb Zurückhaltung. Ein eigenes Plugin kann sinnvoll sein, wenn eine spezielle Isolation oder ein bestimmter Virtualisierungsmechanismus benötigt wird. Vor einem breiten Einsatz sollten jedoch Protokolländerungen, fehlende Support-Zusagen und das Verhalten bei Fehlern getestet werden.
Zusätzlich verändert Version 13.1.0 das Verhalten von Commands mit angehängtem pseudo-tty. Forgejo Runner entfernt diese Terminal-Verbindung, weil sie bei nicht interaktiven Jobs unnötige ANSI- und Steuerdaten in Logs erzeugen kann. Farbige Ausgabe kann dadurch verschwinden. Manche Programme akzeptieren FORCE_COLOR=1. Ein Aufruf wie docker run -it kann dagegen fehlschlagen, weil die Option -t ein Terminal voraussetzt. In diesem Fall muss die Option entfernt werden.
Was bedeutet Alpha-Protokoll?
Die gRPC-Schnittstelle des Plugins ist noch nicht stabil. Forgejo kann Felder und Abläufe ändern, während externe Plugins bereits angepasst werden müssen. Für Tests ist das vertretbar, für kritische Production Workloads sollte eine feste Version mit Rollback-Möglichkeit bereitstehen.
Quelle: Forgejo, „Forgejo Runner v13.1.0“, veröffentlicht am 31. August 2026, forgejo.org/2026-09-runner-release-v131/. Ergänzend: Release Notes und Plugin-Protokoll im Forgejo Runner Repository.