0039: Local-first release with GoReleaser, minisign, a cask and an npm shim
- Status: accepted
- Date: 2026-10-12
Context
The add-distribution change ships vaultfold through GitHub releases, a
Homebrew tap, a Scoop bucket, winget, Linux packages, an npm wrapper and an
install script. ADR 0013 chose GoReleaser and an esbuild-style npm layout in
outline. The details below were decided while building groups 1 to 9; the
reasoning is in openspec/changes/archive/2026-10-30-add-distribution/design.md and the
operational procedure is in docs/release.md.
Decision
- GoReleaser, run through
go run. Releases use GoReleaser OSS pinned to an exact version inpackaging/versions.mkand run withgo run github.com/goreleaser/goreleaser/v2@<version>, so no global install exists to go stale and the Go toolchain pin is the one the Makefile already carries. Publishing steps GoReleaser OSS cannot do (the npm tarballs, the renderedinstall.sh, the release notes and one re-signing ofchecksums.txt) are a post step,scripts/release/release-assets.sh, so GoReleaser creates the GitHub release as a draft and the post step publishes it. - minisign, not cosign keyless. One Ed25519 signature over
checksums.txtcovers every asset. It signs the same way from a laptop and from CI, verifies offline with a public key small enough to embed ininstall.shand print in the README, and is implemented in Go (aead.dev/minisign) sotools/releaseverifies without another tool. cosign keyless would tie the signature to the maintainer's OIDC identity, publish it in a transparency log, differ between laptop and CI, and need network access to verify. It can be added later as a second signature. The secret key is passphrase protected, lives outside the repository and reachestools/releasethroughMINISIGN_SECRET_KEY(a path) andMINISIGN_PASSWORD, never an argument.make releaserefuses to publish when the key is not the private half of the committedpackaging/minisign.pub(tools/release sign --check-key). - A Homebrew cask, not a formula. The release ships prebuilt binaries
and, later, a signed helper app that a formula cannot install. The cask
lives in
bendechrai/homebrew-vaultfold, works on Homebrew for Linux too, and removes the quarantine attribute while binaries are unsigned. - An npm shim. The
vaultfoldpackage is a small JavaScript shim whose platform packages (@vaultfold/<os>-<arch>, installed as optional dependencies) carry the binaries, as esbuild does. There is no install script that downloads anything, sonpm install --ignore-scriptsworks. The platform packages are published before the wrapper. - Local-first release with manual CI.
make releaseruns on the maintainer's Mac: it needs the Apple tools for signing and the maintainer's credentials, injected withvaultfold run(dogfooding). Preflight refuses a dirty tree, a commit that is not av*tag reachable fromorigin/main, a non-macOS host, a private repository, an unfilled license and the wrong signing key, and prints skipped channels instead of failing when an optional credential is missing..github/workflows/release.ymlis the fallback for when that Mac is unavailable:workflow_dispatchwith ataginput only,macos-latest. No workflow is triggered by a tag push (tools/release/internal/workflowsenforces it), so pushing a tag publishes nothing and hosted CI stays manual (see CONTRIBUTING.md). - Signing plans. macOS: GoReleaser's notarize step (quill) signs and notarises the bare binaries with a Developer ID Application certificate and an App Store Connect key; the helper app and the pkg are assembled, signed, notarised and stapled with Apple's own tools on the macOS host. Windows: Authenticode through jsign from a GoReleaser step on the windows builds, with Azure Artifact Signing or an OV certificate on a hardware token or cloud HSM; the daemon's caller check pins the subject and issuer, not a leaf thumbprint. Neither is wired yet (they wait on a D-U-N-S number and a signing identity); until then binaries are ad hoc signed on macOS and unsigned on Windows, the release notes say so, and the minisign signature is the integrity guarantee. The plans are specified by the add-code-signing change, split out of add-distribution on 2026-10-31.
Consequences
- Releases depend on one machine and one person's credentials. The runbook and the CI fallback limit the damage; the key backup is the single point that matters.
- The release pipeline is covered by tests that cannot publish: the shell
tests drive
preflight.shandrelease.shagainst stubs underenv -i. - A lost or leaked signing key means a new key, a new
packaging/minisign.puband an out-of-band announcement; the rotation procedure is in the runbook. - Rejected: cosign keyless as the only signature, a Homebrew formula, a tag-triggered release workflow, and downloading binaries in an npm postinstall script.