Release Process

The nuts-and-bolts of how releases happen. Useful if you’re contributing, tracking specific commits, or planning upgrades.

Versioning

Semantic Versioning strictly:

MAJOR.MINOR.PATCH
Pre-release suffixes: -alpha.N, -beta.N, -rc.N
Example: 1.2.3, 1.3.0-beta.2, 2.0.0-rc.1

What each level means in practice:

Level	Contains
Patch (`1.2.3 → 1.2.4`)	Bug fixes, security patches, no new features
Minor (`1.2 → 1.3`)	New features, deprecations, no breaking changes
Major (`1 → 2`)	Breaking changes, removed deprecated features

Branches

main — always shippable. Every merge passes CI.
release/1.x — created when starting a minor line. Patch releases cherry-picked from main.
feat/*, fix/* — feature/fix branches, merged into main via PR.

No long-lived feature branches. Small PRs merged frequently.

Release cycle

Minor releases

Roughly every 4-6 weeks:

Week 1-3: feature work merged to main
Week 4: feature freeze. Only fixes to main. Cut 1.x.0-beta.1 tag.
Week 5: community beta testing. Bugs fixed, cut 1.x.0-beta.2, etc.
Week 6: when beta is stable, cut 1.x.0 release.

Patch releases

On-demand. When a fix is needed on a shipped version:

Fix lands on main
Cherry-pick onto release/1.x
Tag 1.x.Y+1
Publish

Major releases

~yearly. Requires:

All pending deprecations documented for removal
Migration guide written and reviewed
Staged alpha → beta → RC → stable with at least 4 weeks of RC

Release artifacts

Every tagged release produces:

Artifact	Platforms	Where
Binary	linux/amd64, linux/arm64, linux/arm/v7	GitHub Release
Docker image	linux/amd64, linux/arm64	ghcr.io/blinkmsp/dockmesh:TAG
Agent binary	linux/amd64, linux/arm64, linux/arm/v7	GitHub Release
Release notes		GitHub Release page + /changelog
Checksums file		`SHA256SUMS.txt` on the release
Signed checksums		`SHA256SUMS.txt.asc` (GPG signature by release key)

All binaries are built deterministically — rebuild from the same commit and checksums match.

Build pipeline

Releases are cut via GitHub Actions:

Maintainer tags the commit: git tag v1.2.0 && git push --tags
GitHub Actions triggers:
- golangci-lint run — must pass
- go test ./... — must pass
- Playwright E2E — must pass
- Security scan — no unresolved high/critical in dependencies
- Build binaries for all platforms
- Build Docker image
- Generate checksums
- Sign checksums with release key
- Create GitHub Release with assets
Release notes published from CHANGELOG.md section for that version

No manual publishing — if CI fails, the release doesn’t ship.

Release key

The GPG key used to sign releases:

Key ID: (published on first release)
Fingerprint: (published)
Key storage: hardware token, not committed anywhere

You can verify a release:

curl -fsSL https://github.com/BlinkMSP/dockmesh/releases/download/v1.2.0/SHA256SUMS.txt -o sums.txt
curl -fsSL https://github.com/BlinkMSP/dockmesh/releases/download/v1.2.0/SHA256SUMS.txt.asc -o sums.txt.asc

gpg --recv-keys <release-key-id>
gpg --verify sums.txt.asc sums.txt

If the signature is valid, the checksums are trustworthy, and the binaries match the checksums, you have a verified release.

Emergency security releases

Out-of-band for critical vulnerabilities:

Fix developed privately on a security branch
CVE reserved if applicable
Fix released as a patch to all supported versions
Advisory published simultaneously to GitHub Security Advisories + security@dockmesh.dev subscribers

No public discussion of the vulnerability until release is published.

Supported versions

Only the most recent minor version receives all updates. Older minor versions get critical security fixes for 6 months after the next minor release.

Example: when 1.3.0 ships, 1.2.x gets security fixes for 6 months, then is EOL’d.

Check SECURITY.md for current supported versions.

How to stay current

Watch GitHub releases — get notifications per release
Follow the Changelog RSS — curated, less noise than raw releases
Subscribe to security advisories — GitHub repo → Settings → Notifications → Security alerts

Downgrade policy

Downgrades are not officially supported across database migrations. The server refuses to start if the DB schema is newer than the binary expects.

If you absolutely must downgrade (e.g. a regression you can’t work around):

Stop the server
Restore a pre-upgrade backup
Install the old binary
Start

This loses any data changes made after the upgrade.