Releases

Een release is een getagde momentopname van een repository, eventueel met bijgevoegde binaire artefacten, tarballs of andere bestanden. Releases verschijnen op frem.sh/<org>/<repo>/releases en geven een stabiel, leesbaar overzicht van wat er wanneer is uitgebracht. Ze staan los van het pakketregister: releases bevatten geversioneerde momentopnamen van de broncode en build-artefacten, terwijl containerimages en pakketten van taalecosystemen in het pakketregister thuishoren.

Een release aanmaken in de UI

1. Ga naar Repository → Publicaties → Nieuwe release (frem.sh/<org>/<repo>/releases/new).
2. Kies in het veld Tagnaam een bestaande tag of typ een nieuwe tagnaam om er een aan te maken op de doelbranch of -commit. Semantische versienummers (v1.0.0, v2.3.1-rc.1) worden aanbevolen.
3. Vul de Releasetitel in. Die verschijnt als kop op de releasepagina.
4. Schrijf release notes in het tekstvak. Markdown wordt ondersteund. Neem een samenvatting van de changelog op, brekende wijzigingen, upgrade-instructies en vermeldingen van bijdragers.
5. Voeg release-assets toe door bestanden naar het uploadgebied te slepen (Sleep bestanden hier heen of klik om te uploaden.), of door erop te klikken. Er is geen limiet op het aantal assets; de maximale grootte per asset is 2 GB.
6. Vink Markeren als voorlopige release aan voor release candidates, bèta’s of alles wat nog niet klaar is voor algemeen gebruik. Pre-releases worden apart getoond in de lijst met releases en tellen niet mee voor de aanduiding “latest release”.
7. Klik op Release publiceren om hem direct openbaar te maken, of op Concept opslaan om hem later af te maken. Concepten zijn alleen zichtbaar voor eigenaren van de organisatie en leden met Write- of Admin-toegang tot de repository.

Een release aanmaken vanuit een workflow

Automatiseer releases door te triggeren op gepushte tags. Dit is het gebruikelijke patroon voor projecten die in CI binaries bouwen en die automatisch aan de release willen toevoegen.

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 is een ingebouwd token dat automatisch beschikbaar is in elke workflowjob. Het is beperkt tot de huidige repository en heeft schrijftoegang tot de releases in die repository. Er is niets in te stellen: fremforge maakt het aan bij de start van de job en het verloopt wanneer de job eindigt.

De action forgejo-release met direction: upload maakt de release aan (als die voor de tag nog niet bestaat) en uploadt elk bestand uit dist/ als release-asset.

Assets uploaden vanuit een workflow: via de API

Wil je volledige controle over het aanmaken van de release en het uploaden van assets, roep de API dan rechtstreeks aan vanuit een workflow:

# 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"

Volledige API-naslag: POST /repos/{owner}/{repo}/releases in de REST-API-documentatie.

Release-assets downloaden

Openbare repository’s: release-assets zijn zonder authenticatie openbaar toegankelijk. Download ze rechtstreeks via de asset-URL op de releasepagina.

Privérepository’s: een persoonlijk toegangstoken (PAT) met de scope repo is vereist.

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

Semantische versienummers

Gebruik tagnamen in de vorm vMAJOR.MINOR.PATCH. Consistente versienummers laten tooling en pakketbeheerders de “latest” release correct bepalen en maken de releasepagina makkelijker leesbaar voor menselijke bezoekers.

Pre-release-aanduidingen volgen de SemVer-conventie: v1.2.0-rc.1, v2.0.0-beta.3. Markeer ze als pre-release in de UI of zet "prerelease": true in de API-body.

Een release verwijderen

1. Ga naar Repository → Publicaties.
2. Zoek de release en klik op Bewerken.
3. Scrol naar beneden en klik op Release verwijderen.

Een release verwijderen verwijdert het releaserecord en alle bijgevoegde assets. De onderliggende Git-tag wordt niet verwijderd door deze actie. Wil je de tag ook verwijderen, ga dan naar Repository → Labels (de tags) en verwijder hem daar, of voer git push origin --delete <tag> uit vanuit een lokale clone.

Releases en SBOM’s

Het platform genereert voor elke releasetag een SBOM en voegt die toe als release-asset (bijv. sbom.spdx.json). Het genereren van SBOM’s staat standaard aan; je hoeft niets in te schakelen. Er worden zowel SPDX 2.3- als CycloneDX 1.6-formaten gemaakt.

Zie Beveiliging en toeleveringsketen voor de volledige pipelineconfiguratie en de details over SLSA-provenance.

Releases en het pakketregister

Releases en het pakketregister dienen verschillende doelen:

Containerimages en pakketten van taalecosystemen hebben hun eigen mechanismen voor versies en vindbaarheid (image-tags, npm install, mvn dependency:resolve). Gebruik daarvoor het pakketregister, zodat afnemers ze rechtstreeks met standaardtooling kunnen ophalen. Releases zijn voor artefacten die mensen of scripts expliciet downloaden.

Kruisverwijzingen

• Pakketregister: containerimages, npm-, Maven- en PyPI-pakketten
• Beveiliging en toeleveringsketen: SBOM-generatie, containerscans, SLSA-provenance
• API: naslag van de REST-API voor releases
• CI-runners: runnerlabels en de rechten van GITHUB_TOKEN