DDI/docs/RELEASE.md

Release

Wie ein Release gebaut, signiert und veröffentlicht wird (ADR 0003, ADR 0024).

Ablauf

1. Meilenstein fertig, CI auf main grün.
2. Tag setzen und pushen: git tag -a v0.7.0 -m "M6 Auslieferung" && git push origin v0.7.0.
3. Der Workflow .gitea/workflows/release.yml baut mit make release PACKAGES=1 VERSION=<tag>:
   • Tarballs <binary>_<tag>_linux_<arch>.tar.gz für amd64 und arm64,
   • Pakete <binary>_<version>-1_<arch>.deb und <binary>-<version>-1.<arch>.rpm (nfpm, siehe unten),
   • SHA256SUMS über Tarballs und Pakete,
   • SHA256SUMS.sig, falls das Secret RELEASE_SIGNING_KEY gesetzt ist.
4. scripts/release-upload.sh legt das Gitea-Release an (Tags mit - werden als Vorabversion markiert) und lädt alle Dateien aus dist/ hoch; vorhandene Dateien gleichen Namens werden ersetzt, der Workflow kann also erneut laufen.

Lokal: make release (nur Tarballs), make release PACKAGES=1 bzw. nach make release ein make packages (braucht nfpm), make sign-release RELEASE_SIGNING_KEY_FILE=<pfad>.

Pakete (.deb, .rpm)

scripts/build-packages.sh nimmt die Binaries aus den Tarballs in dist/ (dieselben Dateien, keine zweite Übersetzung) und baut je Binary und Architektur ein .deb und ein .rpm mit nfpm. nfpm wird in der CI von scripts/ci/install-tools.sh in einer festen Version mit Prüfsumme installiert (NFPM_VERSION); lokal genügt ein nfpm im PATH oder make packages NFPM=/pfad/zu/nfpm.

Paket	Inhalt
Name = Binary-Name (BIN_SERVER, BIN_AGENT_DNS, BIN_AGENT_DHCP aus dem Makefile)	/usr/bin/<binary> (0755)
	/usr/lib/systemd/system/<binary>.service (aus deploy/systemd/*.service.in, gerendert mit /usr/bin)
	/usr/share/doc/<binary>/LICENSE (Server proprietär, Agents Apache-2.0)

• Paketversion: Tag ohne v (v0.7.0 → 0.7.0, Release 1); Builds ohne Versions-Tag erhalten 0.0.0-dev.<beschreibung>.
• Die Pakete enthalten keine Konfiguration, legen keine Benutzer an und starten nichts. Die Paket-Skripte rufen nur systemctl daemon-reload auf. Eingerichtet wird mit scripts/install.sh.
• Konfiguration: Vorlage deploy/nfpm/package.yaml.in mit Platzhaltern (ADR 0018). PKG_MAINTAINER, PKG_VENDOR und PKG_HOMEPAGE lassen sich per Umgebung überschreiben.

Signatur

SHA256SUMS.sig ist eine Ed25519-Signatur (64 Byte, binär) über SHA256SUMS, erzeugt mit openssl pkeyutl -sign -rawin. Weil SHA256SUMS alle Artefakte abdeckt, genügt eine Signatur. Der Installer prüft sie mit dem öffentlichen Schlüssel aus seinem Variablenblock.

Schlüsselpaar erzeugen (einmalig, offline)

umask 077
openssl genpkey -algorithm ed25519 -out release-signing.pem    # privat
openssl pkey -in release-signing.pem -pubout -out release-signing.pub.pem

Der private Schlüssel gehört in einen Passwortmanager bzw. auf einen Offline-Datenträger, nicht ins Repository. Wer ihn hat, kann Releases signieren, die jeder Installer annimmt.

Gitea-Secret setzen

Repository → Einstellungen → Actions → Secrets → Secret hinzufügen: Name RELEASE_SIGNING_KEY, Wert = kompletter Inhalt von release-signing.pem (einschließlich der Zeilen -----BEGIN PRIVATE KEY-----/-----END PRIVATE KEY-----).

Der Workflow schreibt den Schlüssel nur für die Dauer des Signierens in eine Datei mit Modus 0600 (umask 077) und löscht sie danach; er wird nie ausgegeben. Ohne Secret entsteht kein SHA256SUMS.sig, der Workflow warnt.

Öffentlichen Schlüssel in den Installer eintragen

In scripts/install.sh im Variablenblock (zwischen # --- names (ADR 0018) --- und # --- end names ---) den Inhalt von release-signing.pub.pem als RELEASE_PUBLIC_KEY_PEM eintragen:

RELEASE_PUBLIC_KEY_PEM="-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEA…
-----END PUBLIC KEY-----"

Ist der Schlüssel gesetzt, bricht der Installer bei fehlender oder ungültiger Signatur ab; ohne Schlüssel prüft er nur die Prüfsummen und weist darauf hin. Der Release-Workflow prüft die frische Signatur mit dem Schlüssel aus scripts/install.sh, damit ein falsch eingetragener Schlüssel schon beim Release auffällt.

Prüfen von Hand

scripts/sign-release.sh verify SHA256SUMS SHA256SUMS.sig release-signing.pub.pem
# entspricht
openssl pkeyutl -verify -pubin -inkey release-signing.pub.pem -rawin -in SHA256SUMS -sigfile SHA256SUMS.sig
sha256sum -c SHA256SUMS

Die CI (Job „Release build (dry run)“) erzeugt bei jedem Lauf einen Wegwerf-Schlüssel und prüft Signieren, Verifizieren sowie die Ablehnung einer veränderten Datei und eines fremden Schlüssels (scripts/sign-release.sh selftest).

Schlüsselwechsel

Neues Schlüsselpaar erzeugen, Secret ersetzen, öffentlichen Schlüssel in scripts/install.sh tauschen, neues Release taggen. Bereits verteilte Installer-Skripte kennen nur den alten Schlüssel und lehnen Releases mit dem neuen ab; sie müssen durch das Skript des neuen Releases ersetzt werden.