Release Process¶

HomeKube uses Semantic Versioning (vMAJOR.MINOR.PATCH) to mark stable cluster configuration snapshots. A release represents a point in time where all Flux-managed resources are known-good.

Versioning scheme¶

Segment	Increment when
MAJOR	Breaking change to cluster setup — e.g. replacing the CNI, changing bootstrap procedure
MINOR	New component or capability added — e.g. deploying a new CNCF tool
PATCH	Bug fix, config tweak, or dependency bump with no user-facing change

Pre-releases use the -rc.N suffix (e.g. v1.1.0-rc.1).

How to cut a release¶

1. Confirm main is ready¶

# All Flux resources reconciled
flux get all -A

# No uncommitted changes
git status

# On main, up to date
git checkout main && git pull

2. Create and push the tag¶

git tag v1.2.3
git push origin v1.2.3

3. GitHub Actions takes over¶

The Release workflow triggers automatically on any v* tag push. It:

Checks out the repo with full history.
Finds the previous tag (falls back to the initial commit for the first release).
Groups commits since the previous tag by Conventional Commit type.
Creates a GitHub Release with the generated changelog.

4. Verify the release¶

Open the Releases page and confirm:

The tag matches the version you pushed.
The changelog lists the expected commits, grouped by type.
The "Full diff" link resolves correctly.

Changelog format¶

The release workflow generates a changelog grouped by commit type:

## What's changed

### Features
- feat(apps): deploy podinfo HelmRelease (a1b2c3d)

### Bug fixes
- fix(identity): correct keycloak realm import path (d4e5f6a)

### Documentation
- docs(adrs): add ADR-016 workload pattern (7b8c9d0)

**Full diff:** https://github.com/MarcSpeckmann/HomeKube/compare/v1.1.0...v1.2.0

Commit types map to sections as follows:

Commit type	Changelog section
`feat`	Features
`fix`	Bug fixes
`docs`	Documentation
`chore`	Chores
`refactor`	Refactoring
anything else	Other

Milestone housekeeping¶

Before cutting a minor or major release, close or move unresolved issues from the corresponding milestone so the milestone progress reaches 100%.

# List open issues in a milestone
gh issue list --repo MarcSpeckmann/HomeKube --milestone "Workloads"