From abcec8e3983d468aeb30d3fbf782873c87363093 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20=C3=9Cbler?= Date: Mon, 22 Dec 2025 09:01:30 +0000 Subject: [PATCH] README geschrieben --- README.md | 172 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 171 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index edf56c9..3d112a7 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,173 @@ # release action -TODO document usage +Gitea/Github-Action, die hilft das Veröffentlichen von Projekten zu automatisieren. + +## Features + - Laden von Credentials und Einrichten der Runner-Umgebung + - Veröffentlichen von Artefakten + - Docker Images + - Python Pakete (wheel, sdist) + - NPM Pakete + - Tarballs + - Ausrollen von Helm-Releases + - Anlegen von Gitea-Releases + - Anlegen von Git-Tags + +## Verwendung +Die Action erwartet eine Beschreibung des zu veröffentlichenden Projekts in `.gitea/release.yaml`. +Darin werden folgende Eigenschaften beschrieben: + - Welche Datei legt die aktuelle Version fest? + - Welche Artefakte sollen veröffentlicht werden? + - Welche Releases sollen wann aktualisiert werden? + +### Beispiel für release.yaml +```#!yaml +# Die Version wird in der Datei Cargo.toml im Hauptverzeichnis des Projekts festgelegt +version_descriptor: Cargo.toml + +artefacts: + # Es soll ein Docker/OCI-Image mit dem Namen masa-images veröffentlicht werden + - type: oci_image + name: masa-images + + # Es soll ein Python-Paket als Wheel veröffentlicht werden + - type: wheel + # Unter diesem Pfad ist das Wheel abgelegt (vor dem Upload in die Registry) + filename: ./scratch/wheels/*.whl + # Diese Datei bestimmt die Version des Pakets. + # Wird synchronisiert mit der Version des Projekts. + version_descriptor: pyproject.toml + +deployments: + # Bei einem Prerelease (push in testing) soll das Helm-Release masa-images-testing + # aktualisiert werden. + - type: helm + release_name: masa-images-testing +``` + +Alle möglichen Einstellungen können [hier](https://gitea.puzzleyou.net/actions/release/src/branch/master/src/release/tests/assets/release.yaml) eingesehen werden. + +### Aufruf im Workflow +Die Action kann die generischen Aufgaben bei einem Release übernehmen. Was sie nicht kann +ist die Artefakte bauen. Wie das zu tun ist muss das Projekt selbst beschreiben. + +Dafür gibt es zwei Möglichkeiten: Die Kurzform in einem Schritt und die Langform in mehreren Schritten. + +#### Langform +Wenn ein Projekt veröffentlicht wird, dann werden folgende Schritt ausgeführt: +- `actions/release/declare`: Hier wird die `release.yaml` gelesen und die Credentials werden geladen. +- `actions/release/sync-versions`: Hier werden die Versionen der Artefakte mit der Version des Projekts synchronisiert. +- Hier muss das Projekt die Artefakte bauen. +- `actions/release/release`: Hier werden die Artefakte veröffentlicht, das Helm-Release aktualisiert und das Gitea-Release angelegt. + +Beispiel: +```#!yaml +name: release +on: + push: + branches: + - master + - testing + +jobs: + check: + uses: ./.gitea/workflows/checks.yaml + + release: + needs: ["check"] + runs-on: action-runner + env: + RUSTC_WRAPPER: sccache + steps: + - uses: actions/checkout@v4 + - uses: https://gitea.puzzleyou.net/actions/release/declare@v0 + - uses: https://gitea.puzzleyou.net/actions/release/sync-versions@v0 + + - name: build image + run: | + nix develop --command just build-image ${RELEASE_IMAGE_TAG} + sccache --show-stats + + - name: build wheel + run: | + mkdir -p ./scratch/wheels + nix develop --command \ + maturin build \ + --release \ + --out ./scratch/wheels/ \ + --strip \ + -m Cargo.toml \ + --compatibility linux \ + --interpreter python3.13 + sccache --show-stats + + - uses: https://gitea.puzzleyou.net/actions/release@v0 +``` + +#### Kurzform +Wenn es nur ein Artefakt gibt und das auch einfach zu bauen ist, dann kann die Kurzform `actions/release` verwendet werden. Das ist der Normalfall. +Im Parameter `build_run` muss das Projekt (in Form eines Bash-Scripts) beschreiben wie die Artefakte gebaut werden. + +Beispiel: +```#!yaml +name: release +on: + push: + branches: + - master + - testing + +jobs: + release: + runs-on: action-runner + steps: + - uses: actions/checkout@v4 + - uses: https://gitea.puzzleyou.net/actions/release@v0 + with: + build_run: docker build -t "${RELEASE_IMAGE_LOCAL_NAME_ALI}" . +``` + +## Umgebungsvariablen +Die Action stellt einige Umgebungsvariablen bereit, die im Workflow nützlich sein können: +- `RELEASE_IMAGE_TAG`: Tag, der Docker/OCI-Images zugewiesen werden muss, damit diese veröffentlicht und in Helm-Releases verwendet werden können. Entspricht momentan dem Commit-Hash. +- `RELEASE_IMAGE_LOCAL_NAME_XXX`: Voller Name eines Docker/OCI-Images mit Tag. +- `RELEASE_IS_PRERELEASE`: Wird gerade ein Release (master/main) oder ein Prerelease (testing) verarbeitet? +- `RELEASE_PROJECT_IS_RELEASED`: Wurde das Projekt schon unter dieser Version veröffentlicht? +- `RELEASE_PROJECT_CURRENT_VERSION`: Aktuelle Version des Projekts, z.B. '2.10.4' +- `RELEASE_PROJECT_PLANNED_VERSION`: "Geplante" Version des Projekts. Entspricht der aktuellen Version mit optionalem Suffix bei Prerelease, z.B. '2.10.4-dev42' + +## Release vs. Prerelease +Die Release-Action kann für Releases (merge in master/main) oder Prereleases (merge in testing) verwendet werden. + +Es unterscheiden sich dann image-tags, git-tags und Versionsnummern der Artefakte. + +### Release +- Image-Tags: `v1`, `v1.2`, `v1.2.3`, `latest`, `master/main.latest` +- Git-Tags: `v1`, `v1.2`, `v1.2.3`, `latest` +- Versionsummern: Wie Projekt + +### Prerelease +- Image-Tags: `v1.2.3-dev4`, `development`, `testing.latest` +- Git-Tags: `v1.2.3-dev4`, `development` +- Versionsnummern: Wie Projekt, mit Suffix `-dev$ACTION_LAUF_NUMMER` + +## Prüfung ob eine Version schon veröffentlicht wurde +Beim Release selbst (merge in main/master) wird geprüft ob eine Version bereits veröffentlicht wurde. +Falls ja, ist das kein Fehler. **ABER** es wird in dem Fall weder ein Docker/OCI-Image hochgeladen, noch ein Helm-Release aktualisiert oder irgendwelche anderen Artefakte veröffentlicht. +Das kann erwünscht sein, wenn eine Änderung nicht ausgerollt werden muss (z.b. Dokumentation angepasst, fixtures verändert, etc.) + +Um bei einem Pull-Request eine Warnung zu sehen, wenn die Version nicht erhöht wurde kann folgender Workflow verwendet werden. Es ist keine Anpassung nötig. +```#!yaml +name: check if project is already released +on: + - pull_request + +jobs: + check: + runs-on: action-runner + steps: + - uses: actions/checkout@v4 + - uses: https://gitea.puzzleyou.net/actions/release/check-is-not-released@v0 +``` + +Bei einem Prerelease (merge in testing) muss die Version nicht angepasst werden. Das geschieht automatisch. \ No newline at end of file