Forgejo Actions Runner einrichten
Push-to-Deploy mit einem eigenen Forgejo Actions Runner auf demselben VPS: eigener Benutzer, kein Docker, enge sudo-Rechte, Secrets in Forgejo.
Geprüft von adrian
am
Nachdem ich meine Git-Repos von GitHub auf eine eigene Forgejo-Instanz umgezogen hatte, war der nächste Schritt, das Deployment von meinem Laptop wegzubekommen. Statt lokal ./scripts/deploy.sh auszuführen und zu hoffen, dass nichts uncommittet ist, sollte git push den Build anstoßen und den Container automatisch ausrollen.
Das Setup
- VPS: eine Debian-Maschine, auf der Forgejo (rootless Podman-Container) und die Website (
/opt/websites/adrian-altner.de, gestartet über einenpodman-compose@-systemd-Service) laufen. - Forgejo: v11 LTS, rootless, unter einem eigenen
git-Systembenutzer. - Ziel: bei jedem Push auf
maindas Production-Image neu bauen und den Service neu starten, alles auf derselben Maschine.
Warum ein eigener Runner-Benutzer
Der Runner führt beliebigen Code aus den Workflow-Dateien aus. Ihn als git-Benutzer laufen zu lassen, der Zugriff auf Forgejos Datenbank und jedes Repo hat, wäre keine gute Idee. Ich habe einen eigenen Systembenutzer mit eigenem Home-Verzeichnis angelegt:
sudo useradd --system --create-home \
--home-dir /var/lib/forgejo-runner \
--shell /bin/bash forgejo-runner
Dieser Benutzer bekommt standardmäßig kein sudo. Weiter unten bekommt er gezielt die Rechte, die der Deploy wirklich braucht.
Runner-Binary installieren
Der Runner ist ein einzelnes statisches Binary aus Forgejos eigener Registry. Ich hole das neueste Release per Skript:
LATEST=$(curl -s https://code.forgejo.org/api/v1/repos/forgejo/runner/releases \
| grep -oE '"tag_name":"v[0-9.]+"' | head -1 | cut -d'"' -f4)
VER="${LATEST#v}"
cd /tmp
curl -L -o forgejo-runner \
"https://code.forgejo.org/forgejo/runner/releases/download/${LATEST}/forgejo-runner-${VER}-linux-amd64"
chmod +x forgejo-runner
sudo mv forgejo-runner /usr/local/bin/
forgejo-runner --version bestätigt v12.9.0, die aktuelle Major-Version, kompatibel mit Forgejo v10, v11 und allem darüber.
Actions in Forgejo aktivieren
Actions sind bei Forgejo standardmäßig aus. Die minimale Konfiguration kommt in die app.ini (bei mir im Volume des rootless Containers unter /home/git/forgejo-data/custom/conf/app.ini):
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://code.forgejo.org
DEFAULT_ACTIONS_URL ist wichtig, weil der Marketplace von GitHub Actions nicht direkt erreichbar ist. Forgejo pflegt eigene Mirrors der gängigen Actions wie actions/checkout unter code.forgejo.org/actions/*. Nach einem Neustart des Containers taucht das Verzeichnis actions_artifacts in den Logs auf.
Runner registrieren
Ein Runner gilt für ein einzelnes Repo, einen Benutzer oder die ganze Instanz. Ich habe mit einer Registrierung für das Repo meiner Website angefangen und dann auf meinen Benutzer umgestellt. So bedient derselbe Runner alle meine Repos, ohne sich neu registrieren zu müssen.
Der Registrierungstoken kommt aus Benutzer-Einstellungen → Actions → Runner → Neuen Runner erstellen:
sudo -iu forgejo-runner /usr/local/bin/forgejo-runner register \
--no-interactive \
--instance https://git.altner.cloud \
--token <REGISTRATION_TOKEN> \
--name arcturus-runner \
--labels "self-hosted:host"
Das Label self-hosted:host bedeutet: „Jobs mit dem Label self-hosted laufen direkt auf dem Host“. Der Runner selbst braucht keine Container-Runtime; Podman ist für die Anwendung ohnehin da.
Einen bestehenden Runner vom Repo auf den Benutzer umstellen: Service stoppen, alten Runner in der Forgejo-Oberfläche löschen, /var/lib/forgejo-runner/.runner lokal entfernen, neuen Token auf Benutzerebene holen, neu registrieren, Service starten. Gleiches Binary, anderer Scope.
Ohne Docker
Beim ersten Start hat sich der Runner geweigert zu laufen:
Error: daemon Docker Engine socket not found and docker_host config was invalid
Auch wenn du nur das Host-Label nutzt, sucht der Runner beim Start einen Docker-Socket. Auf dem Server gibt es nur rootless Podman, also habe ich eine Config-Datei erzeugt und die Docker-Prüfung abgeschaltet:
sudo -iu forgejo-runner /usr/local/bin/forgejo-runner generate-config \
> /tmp/runner-config.yaml
sudo mv /tmp/runner-config.yaml /var/lib/forgejo-runner/config.yaml
sudo chown forgejo-runner:forgejo-runner /var/lib/forgejo-runner/config.yaml
sudo -iu forgejo-runner sed -i \
-e 's|docker_host: .*|docker_host: "-"|' \
-e 's| labels: \[\]| labels: ["self-hosted:host"]|' \
/var/lib/forgejo-runner/config.yaml
Systemd-Service
[Unit]
Description=Forgejo Actions Runner
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=forgejo-runner
Group=forgejo-runner
WorkingDirectory=/var/lib/forgejo-runner
ExecStart=/usr/local/bin/forgejo-runner --config /var/lib/forgejo-runner/config.yaml daemon
Restart=on-failure
RestartSec=5s
NoNewPrivileges=false
ProtectSystem=full
ProtectHome=read-only
ReadWritePaths=/var/lib/forgejo-runner
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now forgejo-runner
Nur die nötigen sudo-Rechte
Der Deploy-Schritt baut ein Podman-Image und startet den systemd-Service neu, der es ausführt. Beides braucht root. Statt dem Runner-Benutzer breites sudo zu geben, habe ich eine eng gefasste Liste unter /etc/sudoers.d/forgejo-runner-deploy angelegt:
forgejo-runner ALL=(root) NOPASSWD: /usr/bin/podman build *, \
/usr/bin/podman container prune *, \
/usr/bin/podman image prune *, \
/usr/bin/podman builder prune *, \
/usr/bin/systemctl restart [email protected], \
/usr/bin/rsync *
visudo -cf prüft die Syntax, bevor du dich versehentlich komplett aus sudo aussperrst.
Der Workflow
Workflows liegen unter .forgejo/workflows/*.yml. Der Deploy macht dasselbe wie mein altes Shell-Skript, nur ohne SSH:
name: Deploy
on:
push:
branches: [main]
workflow_dispatch:
jobs:
deploy:
runs-on: self-hosted
env:
DEPLOY_DIR: /opt/websites/adrian-altner.de
steps:
- uses: actions/checkout@v4
- name: Sync to deploy directory
run: |
sudo rsync -a --delete \
--exclude='.env' \
--exclude='.env.production' \
--exclude='.git/' \
--exclude='node_modules/' \
./ "${DEPLOY_DIR}/"
- name: Build image
run: |
cd "${DEPLOY_DIR}"
sudo podman build \
--build-arg WEBMENTION_TOKEN="${{ secrets.WEBMENTION_TOKEN }}" \
-t localhost/adrian-altner.de:latest .
- name: Restart service
run: sudo systemctl restart [email protected]
- name: Prune
run: |
sudo podman container prune -f 2>/dev/null || true
sudo podman image prune --external -f 2>/dev/null || true
sudo podman image prune -f 2>/dev/null || true
sudo podman builder prune -af 2>/dev/null || true
Secrets bleiben in Forgejo
Alles Sensible, bei mir die API-Tokens für webmention.io und webmention.app, liegt unter Settings → Actions → Secrets und kommt als ${{ secrets.NAME }} in den Job. Forgejo speichert Secrets verschlüsselt, und die Workflow-Logs maskieren ihre Werte. Die Tokens stehen an genau zwei Stellen: in der Workflow-Datei (committet, nur mit Namen) und im verschlüsselten Speicher von Forgejo (nie im Repo).
Der Token für den Build kommt als ARG in den Container, wird nur in der Build-Stage benutzt und steckt nicht im fertigen Image. podman run --rm <image> env | grep -i webmention bestätigt das.
Der eine Stolperstein: Node auf dem Host
Der erste echte Workflow-Lauf ist sofort gescheitert:
Cannot find: node in PATH
actions/checkout@v4 ist eine JavaScript-Action. Bei einem Runner mit Host-Label läuft sie direkt auf dem VPS und braucht Node im PATH. Ein apt install später war der Runner zufrieden:
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo systemctl restart forgejo-runner
Ergebnis
Von git push origin main bis zum Ende der Pipeline (Checkout, rsync, Podman-Build, systemd-Neustart, Prune, Webmention-Pings) vergehen etwa 1 Minute 15 Sekunden. Keine SSH-Keys zu rotieren, kein Laptop beteiligt, kein Rätselraten, welcher Stand live ist.
Der Runner belegt im Leerlauf rund 5 MB RAM und fragt Forgejo alle zwei Sekunden nach neuen Jobs.
Den Runner für neue Projekte wiederverwenden
Weil der Runner für meinen Benutzer registriert ist, braucht CI für ein neues Repo drei Schritte:
- Eine
.forgejo/workflows/deploy.ymlmitruns-on: self-hostedins Repo legen. - Die Secrets des Projekts in den Actions-Einstellungen des Repos anlegen.
- Hat das Projekt einen eigenen systemd-Service,
/etc/sudoers.d/forgejo-runner-deployum eine Zeile fürsystemctl restart <neuer-service>erweitern. Sonst ändert sich auf dem Server nichts.
Die einmalige Arbeit (Benutzer, Binary, Config, systemd-Unit, Node, sudoers) zahlt sich mit jedem weiteren Projekt aus.
Beruht auf
-
Forgejo Actions Runner für self-hosted CI/CD einrichten
(
raw/2026/2026-04-22/forgejo-actions-runner-fuer-self-hosted-ci-cd-einrichten.md) [post]
Mehr dazu
Thema
- Self-Hosting Dienste auf einem Server betreiben, über den du selbst verfügst, statt die gehostete Fassung eines Anbieters zu nutzen.
Baut auf
- Forgejo auf Debian 13 mit rootless Podman Forgejo als rootless Podman-Container unter einem eigenen Benutzer: ein Quadlet für systemd, Caddy davor, SSH auf Port 2222 und die Probleme, auf die ich gestoßen bin.
Nutzt
- Forgejo Git-Plattform zum Selbsthosten: Repositories, Benutzer, SSH-Zugang und CI/CD mit Forgejo Actions und eigenen Runnern. Codeberg läuft damit.
- Podman Container-Engine ohne Hintergrunddienst, unter Linux standardmäßig rootless, mit denselben Befehlen auf dem Mac und auf dem Server.
Erwähnt in
- Astro-Client-Islands unter strikter CSP Warum Astro-Islands unter script-src 'self' still scheitern, wie ich die zwei Hydrations-Inlines per sha256-Hash erlaubt habe und ein Drift-Check beim Deploy.