Releases

Ein Release ist ein getaggter Stand eines Repositorys, optional mit angehängten Binärartefakten, Tarballs oder anderen Dateien. Releases erscheinen unter frem.sh/<org>/<repo>/releases und bieten einen stabilen, gut lesbaren Überblick darüber, was wann ausgeliefert wurde. Sie sind von der Paket-Registry getrennt: Releases enthalten versionierte Quellstände und Build-Artefakte, während Container-Images und Pakete der Sprach-Ökosysteme in die Paket-Registry gehören.

Ein Release in der Oberfläche anlegen

1. Öffne Repository → Releases → Neues Release (frem.sh/<org>/<repo>/releases/new).
2. Wähle im Feld Tag-Name einen bestehenden Tag oder gib einen neuen Tag-Namen ein, um ihn am Ziel-Branch oder -Commit anzulegen. Semantische Versionierung (v1.0.0, v2.3.1-rc.1) wird empfohlen.
3. Setze den Release-Titel. Er erscheint als Überschrift auf der Release-Seite.
4. Schreib die Release Notes in das Textfeld. Markdown wird unterstützt. Nimm eine Zusammenfassung des Changelogs, Breaking Changes, Hinweise zum Upgrade und Danksagungen an Beitragende auf.
5. Hänge Release-Assets an, indem du Dateien auf den Upload-Bereich (Dateien zum Hochladen hier ablegen oder klicken.) ziehst oder darauf klickst. Die Zahl der Assets ist nicht begrenzt; die Größe pro Asset ist auf 2 GB begrenzt.
6. Setze den Haken bei Als Pre-Release kennzeichnen für Release Candidates, Betas oder alles, was noch nicht allgemein einsatzbereit ist. Pre-Releases werden in der Release-Liste getrennt angezeigt und zählen nicht für die Markierung „latest release“.
7. Klicke auf Release veröffentlichen, um es sofort zu veröffentlichen, oder auf Entwurf speichern, um es später fertigzustellen. Entwürfe sehen nur Owner der Organisation und Mitglieder mit Write- oder Admin-Zugriff auf das Repository.

Ein Release aus einem Workflow anlegen

Automatisiere Releases, indem du auf gepushte Tags reagierst. Das ist das übliche Muster für Projekte, die Binärdateien in der CI bauen und sie automatisch an das Release hängen wollen.

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: fremforge
    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: make build

      - name: Create release
        uses: https://code.forgejo.org/actions/forgejo-release@v2
        with:
          direction: upload
          release-dir: dist/
          token: ${{ secrets.GITHUB_TOKEN }}

secrets.GITHUB_TOKEN ist ein eingebautes Token, das jedem Workflow-Job automatisch zur Verfügung steht. Es ist auf das aktuelle Repository beschränkt und hat Schreibzugriff auf die Releases dieses Repositorys. Eine Einrichtung ist nicht nötig: fremforge stellt es beim Start des Jobs bereit, und es läuft ab, wenn der Job endet.

Die Action forgejo-release mit direction: upload legt das Release an (falls es für den Tag noch nicht existiert) und lädt jede Datei aus dist/ als Release-Asset hoch.

Assets aus einem Workflow hochladen: über die API

Für volle Kontrolle über das Anlegen des Releases und das Hochladen der Assets rufst du die API direkt aus einem Workflow auf:

# Create the release
RELEASE_ID=$(curl -sSf \
  -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
  -H "Content-Type: application/json" \
  -d "{\"tag_name\":\"${{ github.ref_name }}\",\"name\":\"${{ github.ref_name }}\"}" \
  https://frem.sh/api/v1/repos/${{ github.repository }}/releases \
  | jq -r '.id')

# Upload an asset
curl -sSf \
  -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @dist/myapp-linux-amd64 \
  "https://frem.sh/api/v1/repos/${{ github.repository }}/releases/${RELEASE_ID}/assets?name=myapp-linux-amd64"

Vollständige API-Referenz: POST /repos/{owner}/{repo}/releases in der REST-API-Dokumentation.

Release-Assets herunterladen

Öffentliche Repositorys: Release-Assets sind ohne Authentifizierung öffentlich zugänglich. Lade sie direkt über die Asset-URL auf der Release-Seite herunter.

Private Repositorys: Ein Personal Access Token (PAT) mit dem Scope repo ist nötig.

curl -L \
  -H "Authorization: Bearer <PAT>" \
  https://frem.sh/<org>/<repo>/releases/download/<tag>/<asset-filename>

Semantische Versionierung

Verwende Tag-Namen der Form vMAJOR.MINOR.PATCH. Eine einheitliche Versionierung lässt Tools und Abhängigkeitsmanager das „neueste“ Release richtig erkennen und macht die Release-Seite für menschliche Besucher leichter lesbar.

Kennungen für Pre-Releases folgen der SemVer-Konvention: v1.2.0-rc.1, v2.0.0-beta.3. Markiere sie in der Oberfläche als Pre-Release oder setze "prerelease": true im API-Body.

Ein Release löschen

1. Öffne Repository → Releases.
2. Such das Release und klicke auf Bearbeiten.
3. Scrolle nach unten und klicke auf Release löschen.

Das Löschen eines Releases entfernt den Release-Eintrag und alle angehängten Assets. Der zugrunde liegende Git-Tag wird dabei nicht gelöscht. Um auch den Tag zu löschen, öffne Repository → Tags und lösche ihn dort, oder führe in einem lokalen Klon git push origin --delete <tag> aus.

Releases und SBOMs

Die Plattform erzeugt für jeden Release-Tag ein SBOM und hängt es als Release-Asset an (z. B. sbom.spdx.json). Die SBOM-Erzeugung ist standardmäßig eingeschaltet; es gibt keinen Schritt zum Aktivieren. Erzeugt werden sowohl SPDX 2.3 als auch CycloneDX 1.6.

Die vollständige Pipeline-Konfiguration und Details zur SLSA-Provenienz findest du unter Sicherheit und Lieferkette.

Releases und die Paket-Registry

Releases und die Paket-Registry dienen unterschiedlichen Zwecken:

Container-Images und Pakete der Sprach-Ökosysteme bringen eigene Mechanismen für Versionierung und Auffindbarkeit mit (Image-Tags, npm install, mvn dependency:resolve). Nutze dafür die Paket-Registry, damit Verbraucher sie mit den üblichen Tools direkt abrufen können. Releases sind für Artefakte gedacht, die Menschen oder Skripte ausdrücklich herunterladen.

Querverweise

• Paket-Registry: Container-Images, npm-, Maven- und PyPI-Pakete
• Sicherheit und Lieferkette: SBOM-Erzeugung, Container-Scans, SLSA-Provenienz
• API: Referenz der Releases-REST-API
• CI-Runner: Runner-Labels und Berechtigungen des GITHUB_TOKEN