Friederich Loheide
83f4223d89
tools/runner/ enthält eine Compose-Datei, eine Beispiel-Konfiguration und eine Schritt-für-Schritt-Anleitung, um den Runner auf dem Server zu registrieren. Der Runner läuft in einem eigenen Verzeichnis und fasst /opt/forgejo nicht an. Abgestimmt auf die vorhandenen Workflows und den Server: - Label-Zuordnung ubuntu-latest -> node:20-bookworm, damit runs-on in ci.yml und release.yml greift - capacity 1 und Speicherlimit, weil der Server nur 4 GB hat - Hinweis darauf, was das Reichen des Docker-Sockets bedeutet, und die Host-Modus-Alternative samt ihrer Grenzen (setup-php braucht Container) Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
3.6 KiB
Forgejo-Actions-Runner einrichten
Ohne registrierten Runner bleiben die Workflows (ci.yml, release.yml) in der
Warteschlange stehen – Forgejo nimmt sie an, es holt sie nur niemand ab.
Die folgenden Schritte laufen als root auf dem Server und legen den Runner in
einem eigenen Verzeichnis an. /opt/forgejo und die dortigen Container bleiben
dabei unberührt.
1. Verzeichnis anlegen
mkdir -p /opt/forgejo-runner/data
cd /opt/forgejo-runner
# docker-compose.yml und config.example.yml aus tools/runner/ hierher kopieren
2. Registrierungs-Token holen
Entweder in der Weboberfläche unter Repository → Einstellungen → Actions → Runner → „Runner erstellen", oder über die API (Token mit Repo-Rechten vorausgesetzt):
curl -s -X POST -H "Authorization: token $FORGEJO_TOKEN" \
https://git.loheide.cloud/api/v1/repos/friloo/Unifi-Voucher-Tool/actions/runners/registration-token
Soll der Runner für alle Repositories zuständig sein, stattdessen
…/api/v1/admin/runners/registration-token verwenden.
Das Token ist kurzlebig und wird nur einmal beim Registrieren gebraucht.
3. Registrieren
docker compose run --rm runner forgejo-runner register --no-interactive \
--instance https://git.loheide.cloud \
--token "<REGISTRIERUNGS-TOKEN>" \
--name "$(hostname)-runner" \
--labels 'ubuntu-latest:docker://node:20-bookworm,ubuntu-22.04:docker://node:20-bookworm'
Die Label-Zuordnung ist wichtig: die Workflows verwenden runs-on: ubuntu-latest,
und dieses Label zeigt hier auf das Image node:20-bookworm. Darin sind Node
(für actions/checkout), Git, curl und unzip bereits enthalten.
4. Konfiguration erzeugen und anpassen
docker compose run --rm runner forgejo-runner generate-config > data/config.yml
Anschließend mindestens diese Werte setzen (Vorlage: config.example.yml):
| Wert | Empfehlung | Grund |
|---|---|---|
runner.capacity |
1 |
der Server hat 4 GB RAM |
runner.timeout |
30m |
die Jobs hier dauern wenige Minuten |
container.force_pull |
false |
spart Bandbreite und Plattenplatz |
cache.enabled |
true |
beschleunigt composer install |
5. Starten
docker compose up -d
docker compose logs -f # sollte "Runner registered successfully" zeigen
Danach erscheint der Runner unter Repository → Einstellungen → Actions → Runner
als „idle", und der nächste Push auf main baut das Release-ZIP.
Was der Runner darf – bitte bewusst entscheiden
Der Runner bekommt den Docker-Socket des Hosts gereicht. Damit kann jeder Workflow, der auf diesem Runner läuft, Container mit Root-Rechten starten – das entspricht faktisch Root auf dem Server. Für ein privates Repository, in dem nur eigene Workflows laufen, ist das üblich und vertretbar. Sobald Fremde Pull Requests öffnen können, sollte der Runner stattdessen auf einer separaten Maschine oder in einer VM laufen.
Alternative ohne Docker-Socket: Runner im Host-Modus (ubuntu-latest:host).
Dann laufen die Jobs direkt auf dem Server, ohne Container – dafür müssen Node,
Git und PHP dort installiert sein, und die Jobs sehen das Dateisystem des Hosts.
Für release.yml würde das reichen, für ci.yml (PHP 7.4 und 8.2 über
shivammathur/setup-php) nicht.
Speicherbedarf im Blick behalten
node:20-bookworm belegt rund 1 GB auf der Platte, die Job-Container brauchen
kurzzeitig einige hundert MB RAM. Bei 4 GB Gesamtspeicher sollte neben Forgejo,
Caddy und der Datenbank nur ein Job gleichzeitig laufen (capacity: 1).
Aufräumen gelegentlich mit:
docker image prune -f
docker builder prune -f