Release Workflow

Release Workflow

Trove uses GitHub Actions, release-please, GoReleaser, and GHCR.

This page describes the intended flow for maintainers.

Normal flow

branch -> PR -> CI -> merge to main
          |
          v
release-please updates release PR
          |
          v
merge release PR when ready
          |
          v
v* tag exists or is created by release automation
          |
          v
GoReleaser publishes GitHub Release and GHCR images

CI

The CI workflow runs on pushes and PRs.

It checks:

• gofmt
• go vet
• golangci-lint
• unit tests and race tests
• cross-platform release build
• GoReleaser configuration
• Dockerfile runtime drift
• release-surface version drift

A separate required security job runs govulncheck and gitleaks. PR titles are also checked for conventional-commit format.

The protected branch expects the CI job name configured in GitHub branch protection. If that job name changes, branch protection needs updating too.

Commit prefixes

Release versioning follows conventional-style prefixes:

Prefix	Effect
fix:	patch material
feat:	minor material
feat!: or BREAKING CHANGE:	major material
docs:, ci:, chore:	no version bump by themselves

Release-please

Release-please maintains the release PR.

That PR usually updates:

• CHANGELOG.md
• .release-please-manifest.json

Do not treat the release PR as a feature branch. It is release paperwork.

Merging it updates the manifest/changelog and release-annotated install surfaces. release-tag.yml detects the manifest change and creates the matching vX.Y.Z tag. There is no normal manual-tag step.

GoReleaser

GoReleaser runs from a pushed v* tag.

It publishes:

• GitHub Release notes/assets
• checksums
• binaries
• GHCR images and multi-arch manifests

The release-please and tag workflows use the repository's RELEASE_PLEASE_TOKEN, not the default GITHUB_TOKEN, so GitHub is allowed to trigger the downstream CI and tag-based release workflows.

Verify releases

After a release:

gh release view vX.Y.Z
gh release list

Check container images:

docker pull ghcr.io/techdox/trove-server:X.Y.Z
docker pull ghcr.io/techdox/trove-agent-docker:X.Y.Z
docker pull ghcr.io/techdox/trove-agent-k8s:X.Y.Z
docker pull ghcr.io/techdox/trove-agent-proxmox:X.Y.Z

GHCR visibility gotcha

New GHCR packages can default private even when the repository is public.

If a new image is added and users cannot pull it, check the package visibility in GitHub's UI.

Latest release gotcha

GitHub's latest marker is based on release state, not always what humans expect.

After unusual release edits, check:

gh release list

If needed:

gh release edit vX.Y.Z --latest

Emergency manual tag

If automation fails but the code is ready and the release version is known:

git tag -a vX.Y.Z -m "release vX.Y.Z"
git push origin vX.Y.Z

Use this as a fallback, not the normal habit.