Forgejo Runner

Forgejo Runner mit Podaman rootles containeren unter Debian bookworm (12). Der Runner führt definierte Arbeitsabläufe (Workflows / Actions) des Git Servers Forgejo aus.

Voraussetzung ist ein laufendes Debian System und eine laufende Forgejo Instanz.

Installation

Neuster Version des Runners von code.forgejo.org herunterladen
Die Go Binärdatei als /usr/local/bin/forgejo-runner ablegen und Berechtigungen setzen damit die Datei ausgeführt werden kann.

_url=$(\
curl https://code.forgejo.org/api/v1/repos/forgejo/runner/releases/latest | \
jq '.assets[] | 
    select(.name|match("^forgejo-runner-.*-linux-amd64$")) | 
    .browser_download_url' | \
sed 's/"//g')
curl \
    -o /usr/local/bin/forgejo-runner \
    $_url
chmod 755 /usr/local/bin/forgejo-runner
chown root:root /usr/local/bin/forgejo-runner

Podman installieren

apt install podman

Gruppe und Benutzer anlege. Verwendet man einen normalen (nicht Systemuser) spart man es sich, um die subuid und subgid für die Container selbst kümmern zu müssen. Für den neuen User muss linger aktiviert werden, damit Prozesse des Users auch ohne aktiver Benutzersession weiter laufen.

adduser \
    --home /var/lib/forgejo-runner \
    --disabled-password \
    --comment 'Forgejo Runner' \
    forgejo-runner
loginctl enable-linger forgejo-runner

Notwendige Verzeichnisse anlegen. Der Ordner persistent ist optional um den Containern zu ermöglichen Daten abzulegen, wie z.B. Bibliotheken die immer wieder zum Bauen benötigt werden. Dient hier als Beispiel und Alternative für den Cache Service des Runners.

install -o forgejo-runner -g forgejo-runner -m 755 -d /etc/forgejo-runner
install -o forgejo-runner -g forgejo-runner -m 755 -d /var/cache/forgejo-runner
install -o forgejo-runner -g forgejo-runner -m 755 -d /var/cache/forgejo-runner/persistent
install -o forgejo-runner -g forgejo-runner -m 755 -d /var/lib/forgejo-runner
ln -s /var/cache/forgejo-runner /var/lib/forgejo-runner/.cache
chown -h forgejo-runner:forgejo-runner /var/lib/forgejo-runner/.cache

Konfiguration

Konfiguration für den Runner generieren und entsprechend anpassen.

forgejo-runner generate-config > /etc/forgejo-runner/config.yml
chown forgejo-runner:forgejo-runner /etc/forgejo-runner/config.yml

Unter envs werden Umgebungsvariablen definiert die in jedem Container benötigt werden so z.B. für den Zugriff über einen Proxy. Mit den labels wird festgelegt welche Container der Runner bereitstellen soll. Es sollte Container sein die NodeJS bereits mitbringen da die meisten Actions dies voraussetzen so z.B. die wohl wichtigste Action checkout. Unter container kann auch das wie oben beschriebene optionale persistent Verzeichnis in jeden Container eingebunden werden.

runner:
  envs:
    http_proxy=http://127.0.0.1:3128
    https_proxy=http://127.0.0.1:3128
    no_proxy=localhost,127.0.0.1,git.example.net
  labels:
    - bookworm:docker://node:bookworm
    - bullseye:docker://node:bullseye
container:
  options:
    -v /var/cache/forgejo-runner/persistent/:/var/cache/persistent:rw
  valid_volumes:
    - /var/cache/forgejo-runner/persistent/

Systemd service anlegen /etc/systemd/system/forgejo-runner.service. Der Runner benötigt die Umgebungsvariable DOCKER_HOST diese muss auf den Socket von Podman zeigen, für den User mit dem der Runner läuft. Die User ID des oben angelegten Users im Pfad /run/user/<id>/podman/ anpassen.

[Unit]
Description=Forgejo Runner

[Service]
User=forgejo-runner
Group=forgejo-runner
WorkingDirectory=/var/lib/forgejo-runner
Environment="DOCKER_HOST=unix:///run/user/1001/podman/podman.sock"
ExecStart=forgejo-runner --config /etc/forgejo-runner/config.yml daemon
ExecReload=/bin/kill -s HUP $MAINPID
Restart=on-failure
TimeoutSec=0
RestartSec=10

[Install]
WantedBy=multi-user.target

Podman Socket aktivieren, über den der Runner mit Podman kommuniziert.

ln -s /usr/lib/systemd/user/podman.socket \
    /etc/systemd/user/sockets.target.wants/podman.socket
install -o root -g root -m 755 -d /etc/systemd/user/podman.service.d

Benötigt man einen Proxy um an das gewünschte Container Register zu kommen muss man dem Podman Service noch die Variablen für den Zugriff über den Proxy zu Verfügung stellen. Dafür das Verzeichnis anlegen.

install -o root -g root -m 755 -d /etc/systemd/user/podman.service.d

Und in der Datei /etc/systemd/user/podman.service.d/override.conf die Variablen eintragen.

[Service]
Environment="http_proxy=http://127.0.0.1:3128"
Environment="https_proxy=http://127.0.0.1:3128"
Environment="no_proxy=localhost,127.0.0.1,git.example.net"

Nun die neuen Konfigurationen für Systemd einlesen und den Runner starten.

systemctl daemon-reload
systemctl start forgejo-runner
systemctl enable forgejo-runner

Damit linger für den User auch funktioniert sollte man das System an dieser Stelle neu starten.

Runner registrieren

Mit openssl rand -hex 20 den secret für den Runner erzeugen.

Als User forgejo-runner das folgende Kommando im home Verzeichnis des Users (/var/lib/forgejo-runner), ausführen, wobei --instance die URL zur laufenden Forgejo Instanz ist. Dies erzeugt die Datei .runner.

cd /var/lib/forgejo-runner
forgejo-runner create-runner-file \
    --instance https://git.example.net \
    --name runner01
    --secret <secret>

Auf dem System auf dem die Forgejo Instanz läuft dann den Runner registrieren. Den Befehl mit dem User ausführen mit dem die Instanz läuft und mit --config den Pfad zur Konfiguration der Instanz angeben und --secret des Runners.

forgejo \
    --config /etc/forgejo/app.ini \
    forgejo-cli actions register --name runner01 \
    --secret <secret>

Der Runner sollte nun auch im Forgejo GUI unter Administration -> Actions -> Runner gelistet werden und kann nun genutzt werden.