Starlab

Go CLI Release Kit

Release a Go command-line tool the careful way: GoReleaser config, an installer that checks what it downloads, and the scripts around them.

Buy on Polar: $24 One-time purchase · v0.1.0 · instant download via Polar

Go CLI Release Kit cover
Output from a real test run, not a mock-up.

Who it is for

You wrote a command-line tool in Go and people want to install it. The GoReleaser documentation is good and free, and a working .goreleaser.yaml takes an afternoon. The rest takes longer: a version command that prints the real commit, an install.sh you would not be embarrassed to pipe from curl, a checksum story, CI that releases on a tag, a Homebrew formula that does not have an empty hash in it.

This kit is a repository skeleton you copy in and rename. Everything in it has been run in a clean container, and the output is included so you can see what "works" meant.

What is in it

  • .goreleaser.yaml for Linux, macOS and Windows on amd64 and arm64. Static builds, -trimpath, version, commit and commit date injected, a checksums file, and a changelog grouped by Conventional Commit prefix.
  • install.sh, a verifying installer with a pinned-version option and optional GPG signature checking.
  • A reproducibility checker that builds twice in separate clean environments and compares the results.
  • A version-bump script that reads your commits and picks the next tag.
  • Homebrew and Scoop generators that build the formula and manifest from your real checksums.
  • CI templates for GitHub Actions and GitLab: lint, test with the race detector, release on tag.
  • An example CLI in the standard library only, with tests, and a step-by-step first-release guide with a checklist.

What the installer refuses

An installer that downloads a binary and runs it is a good place to be strict. In the tests, install.sh stops, installs nothing and leaves an existing install untouched when:

  • the archive does not match its SHA-256 (we tamper with one to check),
  • the checksums file has no entry for the archive, or has the entry twice,
  • the checksums file is missing, or the release does not exist,
  • the URL is plain http,
  • the version string is malformed or empty,
  • the platform is not one you built for. Architecture detection is tested with a fake uname, including armv7, i686, riscv64, FreeBSD and Windows shells.

With a GPG key configured, a wrong key, a modified checksums file, a missing signature and a missing key file are all refused as well, so the signature protects the checksums file itself.

Reproducible builds, checked

repro-check.sh clones the repository twice, in different directories, with an empty environment and a fresh Go cache, two seconds apart, and compares binaries, archives and the checksums file. For the example project, 13 of 13 files were identical. Two deliberate mistakes, embedding the build time in the ldflags and leaving out -trimpath, each made every file differ. So the check fails when it should.

Numbers

The -s -w linker flags cut archive size by roughly half on this example: the Linux amd64 archive is 770,338 bytes with them and 1,531,872 without. Build times depend heavily on cache state; the README lists them with the setup.

How it was tested

183 automated checks in a clean Linux container with GoReleaser v2.20.0, plus a build and test pass of the example on Go 1.22. The checks include a snapshot release producing six archives, running the produced Linux binary and comparing its --version output, checking the checksums file against the archives, a tagged build for the changelog, about 25 cases for the version-bump script on temporary git repositories, and actionlint on the GitHub workflows.

Requirements

Go, git and GoReleaser OSS. Docker if you want to run the test harness.

FAQ

Why not just use the GoReleaser docs?

You can. The docs cover GoReleaser. This kit covers what sits around it and checks that the pieces work together.

Does it support GitLab?

Yes. There is a GitLab CI template, with notes on the token setup.

Can I use my own module path and names?

Yes. The first-release guide lists every place to rename.

License

Use it in your own projects. The skeleton's own LICENSE file is yours to replace. Please do not resell the kit.

Changelog

  • 0.1.0: first release.

Read more

Get it

Buy on Polar: $24

Payment, tax and invoices are handled by Polar as merchant of record. You receive a download link after checkout.