Skip to content

Releases and Versioning

Jump to bottom
Kris Armstrong edited this page May 19, 2026 · 1 revision

Releases & Versioning

SemVer + Conventional Commits

The Stem follows SemVer. Versions are computed automatically from conventional-commit history via release-please.

Commit prefix Bump
feat: minor
fix:, perf:, refactor: patch
chore:, docs:, test:, ci: none
BREAKING CHANGE: footer or ! major

Don't manually push v* tags. release-please opens a "release PR" on every push to main; merging that PR creates the tag, the GitHub Release, the CHANGELOG entry, and triggers artifact builds.

Release pipeline

  1. PR merges to main
  2. release-please workflow opens / updates the release PR
  3. The release PR is reviewed and merged
  4. release-please pushes the tag
  5. release.yml fires on the tag push, builds + signs + uploads via goreleaser-cross
  6. SLSA L3 provenance attestation generated and attached

End-to-end ~10-15 minutes from release-PR merge to a signed + attested GitHub Release.

Per-release artifacts

Every tag produces:

  • Platform/format combinations:
    • linux × {amd64, arm64} as .deb, .rpm, .tar.gz
    • darwin × {amd64, arm64} as .tar.gz + .pkg
    • windows × {amd64, arm64} as .zip
  • Cosign keyless OIDC signature per artifact
  • syft SBOM per archive
  • stem-slsa-provenance.intoto.jsonl — SLSA L3 attestation
  • checksums.txt + cosign signature

CGO build matrix

Linux builds use CGO_ENABLED=1 so the C dataplane (libreflector.a from src/dataplane/) is statically linked for the reflector role.

macOS / Windows builds use CGO_ENABLED=0 — pure-Go networking via gopacket. The reflector role is unavailable on those platforms (the binary still ships but stem reflect returns "CGO dataplane not available on this platform").

Verify a release

gh release download vX.Y.Z --repo krisarmstrong/stem --pattern '*-linux-amd64.tar.gz*'

cosign verify-blob \
  --bundle stem-X.Y.Z-linux-amd64.tar.gz.cosign.bundle \
  --certificate-identity 'https://github.com/krisarmstrong/stem/.github/workflows/release.yml@refs/tags/vX.Y.Z' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  stem-X.Y.Z-linux-amd64.tar.gz

slsa-verifier verify-artifact \
  --provenance-path stem-slsa-provenance.intoto.jsonl \
  --source-uri github.com/krisarmstrong/stem \
  --source-tag vX.Y.Z \
  stem-X.Y.Z-linux-amd64.tar.gz

Backfilled provenance

v0.12.0 and v0.12.1 shipped binaries without SLSA attestations because of an upstream bug in slsa-github-generator v2.1.0. The fix landed in #208; backfill for those older tags is tracked as a follow-up.

Clone this wiki locally