From b239e51a79c155a4f749f240c4e81aa873026113 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 | 195 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 194 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index edf56c9..1efbbdc 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,196 @@ # release action +Gitea/Github-Action, die hilft das Veröffentlichen von Projekten zu +automatisieren. -TODO document usage +## 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](/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.