SNLO – Spittank.net Ladeorganisation – Forgejo, Pages und Registry¶

SNLO – Spittank.net Ladeorganisation enthält Forgejo-Actions-Workflows unter .forgejo/workflows/:

Workflow	Auslöser	Aufgabe
`ci.yml`	Push auf `main`, Pull Request	`validate`: nur Anwendungstests/Syntax/Alembic; `docs` auf `main`: Zensical-Build und Pages-Veröffentlichung
`release.yml`	Tag `v*`	vollständige Validierung und Multi-Arch-Image in der Forgejo-Registry

Der normale validate-Job ruft scripts/validate-release.sh nicht auf und führt keinerlei Dokumentationsprüfung aus. Dokumentation wird ausschließlich im separaten docs-Job gebaut.

Der normale CI-Workflow baut ausdrücklich kein Docker-Image. Container werden ausschließlich bei einem Release-Tag durch release.yml gebaut und veröffentlicht.

Voraussetzungen in Forgejo¶

Im Repository müssen Actions aktiviert und ein Runner mit dem Label ubuntu-latest verfügbar sein.

Für ci.yml genügen Python 3.12, Node.js 22 und die durch die Actions eingerichteten Werkzeuge. Ein Docker-Daemon ist nicht erforderlich. Der Dokumentationsjob ist bewusst vom Anwendungs-Validierungsjob getrennt.
Für release.yml benötigt der Runner Docker beziehungsweise einen erreichbaren Docker-Daemon und muss QEMU-/Buildx-Schritte für linux/amd64 und linux/arm64 zulassen.

Secrets¶

Unter Repository → Einstellungen → Actions → Secrets:

Secret	Inhalt
`REGISTRY_USER`	Forgejo-Benutzer oder Bot für die Registry
`REGISTRY_TOKEN`	persönlicher Zugriffstoken beziehungsweise Registry-Token

Bei aktivierter Zwei-Faktor- oder OAuth-Anmeldung muss ein Token statt des Kontopassworts verwendet werden. Die Secrets werden nur im Tag-Release verwendet.

Optionale Registry-Variablen¶

Unter Repository → Einstellungen → Actions → Variablen können folgende Werte überschrieben werden:

Variable	Vorgabe im Workflow	Bedeutung
`REGISTRY_HOST`	`dev.spittank.org`	Host der Forgejo-Registry
`REGISTRY_NAMESPACE`	Repository-Eigentümer	einzelner Forgejo-Benutzer oder eine Organisation, ohne Schrägstrich

Für Pages ist keine Variable und keine eigene Domain erforderlich. Die Repository-Dokumentation wird fest veröffentlicht unter:

https://daniel.snii.de/snlo/

Ohne abweichende Registry-Variablen entsteht das Image:

dev.spittank.org/<repository-owner>/snlo:<version>

Zensical lokal¶

Dokumentationsabhängigkeiten installieren:

python3 -m venv .venv-docs
. .venv-docs/bin/activate
pip install -r requirements-docs.txt

Nach site/ bauen:

zensical build --config-file zensical.toml

Lokale Vorschau:

zensical serve --config-file zensical.toml

Die Markdown-Quellen liegen unter docs/. Navigation, Sprache, Wortmarke, kanonische Repository-Pages-URL und Ausgabeziel stehen fest in zensical.toml.

Pages-Veröffentlichung¶

Nach erfolgreicher Anwendungsvalidierung baut der separate docs-Job bei einem Push auf main die Dokumentation direkt mit Zensical und veröffentlicht site/ mit:

- name: Dokumentation über git-pages veröffentlichen
  uses: https://codeberg.org/git-pages/action@v2
  with:
    site: "https://daniel.snii.de/snlo/"
    token: "${{ forge.token }}"
    source: "site/"

Pull Requests veröffentlichen nicht. Eine Custom Domain wird nicht verwendet.

Container-Release¶

Ein Release wird durch einen stabilen SemVer-Tag ausgelöst. Der Tag muss exakt vX.Y.Z entsprechen und dieselbe Version wie pyproject.toml enthalten; andernfalls bricht der Workflow vor der Registry-Anmeldung ab:

git tag v0.5.12
git push origin v0.5.12

Der Release-Workflow erzeugt ein OCI-Image für:

linux/amd64
linux/arm64

und veröffentlicht zwei Tags:

dev.spittank.org/daniel/snlo:0.5.12
dev.spittank.org/daniel/snlo:latest

Der konkrete Eigentümer richtet sich nach REGISTRY_NAMESPACE beziehungsweise dem Repository-Eigentümer.

Deployment aus der Registry¶

In .env:

SNLO_IMAGE=dev.spittank.org/daniel/snlo:0.5.12
SNLO_PULL_POLICY=always

Bei privatem Paket zunächst anmelden:

docker login dev.spittank.org

Dann aktualisieren:

docker compose pull migrate api worker
docker compose up -d

migrate, api und worker verwenden dasselbe Image. Nur db stammt weiterhin direkt aus dem offiziellen PostgreSQL-Image.

Sicherheitsgrenzen¶

Pull-Request-Jobs erhalten keine Registry-Secrets und veröffentlichen nichts.
Checkout persistiert keine Repository-Zugangsdaten.
Registry-Zugangsdaten werden ausschließlich dem Tag-Release-Job übergeben.
Pages wird nur nach erfolgreicher Validierung und nur von main veröffentlicht.
Docker, QEMU und Buildx werden ausschließlich im Release-Workflow verwendet.
Das Release-Image erhält OCI-Labels für Quelle, Revision, Version und Titel.