# release action 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.