Skip to content

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 in packaging/versions.mk and run with go 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 rendered install.sh, the release notes and one re-signing of checksums.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.txt covers every asset. It signs the same way from a laptop and from CI, verifies offline with a public key small enough to embed in install.sh and print in the README, and is implemented in Go (aead.dev/minisign) so tools/release verifies 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 reaches tools/release through MINISIGN_SECRET_KEY (a path) and MINISIGN_PASSWORD, never an argument. make release refuses to publish when the key is not the private half of the committed packaging/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 vaultfold package 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, so npm install --ignore-scripts works. The platform packages are published before the wrapper.
  • Local-first release with manual CI. make release runs on the maintainer's Mac: it needs the Apple tools for signing and the maintainer's credentials, injected with vaultfold run (dogfooding). Preflight refuses a dirty tree, a commit that is not a v* tag reachable from origin/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.yml is the fallback for when that Mac is unavailable: workflow_dispatch with a tag input only, macos-latest. No workflow is triggered by a tag push (tools/release/internal/workflows enforces 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.sh and release.sh against stubs under env -i.
  • A lost or leaked signing key means a new key, a new packaging/minisign.pub and 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.