Go CLI Release Kit

Für wen es ist

Sie haben ein Kommandozeilentool in Go geschrieben, und andere wollen es installieren. Die GoReleaser-Dokumentation ist gut und kostenlos, und eine funktionierende .goreleaser.yaml ist in einem Nachmittag geschrieben. Der Rest dauert länger: ein Version-Befehl, der den echten Commit ausgibt, ein install.sh, den Sie ohne Scham per curl pipen lassen würden, ein Konzept für Prüfsummen, eine CI, die bei einem Tag released, und eine Homebrew-Formel ohne leeren Hash.

Dieses Kit ist ein Repository-Gerüst, das Sie hineinkopieren und umbenennen. Alles darin lief in einem sauberen Container, und die Ausgabe liegt bei, damit Sie sehen, was „funktioniert“ hier bedeutet hat.

Was drin ist

• .goreleaser.yaml für Linux, macOS und Windows auf amd64 und arm64. Statische Builds, -trimpath, Version, Commit und Commit-Datum eingebettet, eine Prüfsummendatei und ein Changelog, gruppiert nach Conventional-Commit-Präfix.
• install.sh, ein prüfender Installer mit Option für eine feste Version und optionaler GPG-Signaturprüfung.
• Ein Reproduzierbarkeits-Check, der zweimal in getrennten sauberen Umgebungen baut und die Ergebnisse vergleicht.
• Ein Skript für den Versionssprung, das Ihre Commits liest und den nächsten Tag wählt.
• Homebrew- und Scoop-Generatoren, die Formel und Manifest aus Ihren echten Prüfsummen erzeugen.
• CI-Vorlagen für GitHub Actions und GitLab: Lint, Tests mit dem Race Detector, Release bei Tag.
• Ein Beispiel-CLI nur mit der Standardbibliothek, mit Tests, und eine Schritt-für-Schritt-Anleitung für das erste Release mit Checkliste.

Was der Installer ablehnt

Ein Installer, der ein Binary herunterlädt und ausführt, ist ein guter Ort für Strenge. In den Tests bricht install.sh ab, installiert nichts und lässt eine vorhandene Installation unangetastet, wenn:

• das Archiv nicht zu seinem SHA-256 passt (wir manipulieren dafür eines),
• die Prüfsummendatei keinen Eintrag für das Archiv hat oder den Eintrag doppelt enthält,
• die Prüfsummendatei fehlt oder das Release nicht existiert,
• die URL ein einfaches http ist,
• der Versionsstring fehlerhaft oder leer ist,
• die Plattform keine ist, für die Sie gebaut haben. Die Erkennung der Architektur ist mit einem gefälschten uname getestet, darunter armv7, i686, riscv64, FreeBSD und Windows-Shells.

Ist ein GPG-Schlüssel konfiguriert, werden auch ein falscher Schlüssel, eine veränderte Prüfsummendatei, eine fehlende Signatur und eine fehlende Schlüsseldatei abgelehnt. Die Signatur schützt also die Prüfsummendatei selbst.

Reproduzierbare Builds, geprüft

repro-check.sh klont das Repository zweimal in verschiedene Verzeichnisse, mit leerer Umgebung und frischem Go-Cache, im Abstand von zwei Sekunden, und vergleicht Binaries, Archive und die Prüfsummendatei. Beim Beispielprojekt waren 13 von 13 Dateien identisch. Zwei absichtliche Fehler, die Build-Zeit in den ldflags und das Weglassen von -trimpath, führten jeweils dazu, dass sich jede Datei unterschied. Der Check schlägt also an, wenn er soll.

Zahlen

Die Linker-Flags -s -w halbieren in diesem Beispiel die Archivgröße ungefähr: Das Linux-amd64-Archiv hat mit ihnen 770,338 Byte und ohne sie 1,531,872. Die Build-Zeiten hängen stark vom Cache-Zustand ab. Das README listet sie zusammen mit dem Aufbau auf.

So wurde getestet

183 automatische Checks in einem sauberen Linux-Container mit GoReleaser v2.20.0, dazu ein Build- und Testlauf des Beispiels mit Go 1.22. Die Checks umfassen ein Snapshot-Release mit sechs Archiven, das Ausführen des erzeugten Linux-Binarys mit Vergleich seiner --version-Ausgabe, den Abgleich der Prüfsummendatei mit den Archiven, einen getaggten Build für das Changelog, rund 25 Fälle für das Skript zum Versionssprung in temporären Git-Repositories und actionlint für die GitHub-Workflows.

Voraussetzungen

Go, git und GoReleaser OSS. Docker, wenn Sie das Test-Harness ausführen wollen.

Häufige Fragen

Warum nicht einfach die GoReleaser-Doku nutzen?

Können Sie. Die Doku behandelt GoReleaser. Dieses Kit behandelt, was darum herum liegt, und prüft, dass die Teile zusammen funktionieren.

Unterstützt es GitLab?

Ja. Es gibt eine GitLab-CI-Vorlage mit Hinweisen zur Token-Einrichtung.

Kann ich meinen eigenen Modulpfad und eigene Namen verwenden?

Ja. Die Anleitung für das erste Release listet jede Stelle auf, die Sie umbenennen müssen.

Lizenz

Sie dürfen es in Ihren eigenen Projekten einsetzen. Die LICENSE-Datei des Gerüsts können Sie durch Ihre eigene ersetzen. Bitte verkaufen Sie das Kit nicht weiter.

Änderungsprotokoll

• 0.1.0: erstes Release.

Weiterlesen

• Verify a downloaded binary: checksums, GPG, minisign, cosign (Englisch)
• Reproducible Go builds: build twice, compare the hashes (Englisch)
• A GoReleaser v2 config for a small Go CLI, line by line (Englisch)
• What a curl | sh installer for a Go binary should refuse (Englisch)

Herunterladen

Bei Polar kaufen: $24

Zahlung, Steuern und Rechnung übernimmt Polar als Merchant of Record. Den Download-Link erhalten Sie nach dem Checkout.