---

name: release description: Playbook for cutting a proxyforward release — a tag drives the pipeline, which stops at a draft you must smoke-test and publish by hand. Releases are an escalation trigger: confirm with the human first.

Cut a release (playbook F)

Cutting or tagging a release is an escalation trigger — confirm with the human.

.github/workflows/release.yml does the build. It stops at a draft on purpose: the smoke test below is the part that cannot be automated, and a draft is what gives you the chance to run it before anyone can download the binary.

1. Clean tree on master; CI green (go test ./..., cd frontend && npm run build).
2. Tag and push: git tag vX.Y.Z && git push origin vX.Y.Z. The workflow builds the exe and the NSIS installer, stamps the version via -ldflags into internal/version, asserts --version reports the tag, writes SHA256SUMS.txt and an SPDX SBOM, and attaches a build-provenance attestation.
3. Smoke the draft's artifacts — download them, don't trust the build:
   • proxyforward.exe --version shows vX.Y.Z.
   • The exe launches to the wizard/console.
   • The installer installs, launches, and uninstalls.
   • A loopback pair (gateway + agent headless, docs/agent/commands.md) moves bytes.
4. Publish the draft in the GitHub Releases UI.
5. Update README + root CLAUDE.md if commands or claims changed.

What can go wrong

• A missing installer is silent. wails build -nsis exits 0 and just skips the installer when makensis isn't on PATH, so the workflow installs NSIS itself and then asserts the file exists. If that assert fires, the toolchain broke — don't "fix" it by dropping -nsis.
• The binaries are unsigned (no certificate). SmartScreen warns on first run. The honest substitute is the attestation: gh attestation verify <exe> -R xeri/proxyforward.
• Windows only. The linux/macOS artifacts CI builds are never release assets — the engine can't start there (see the Reality check in CLAUDE.md).