How to publish a version of the frontend to GHCR.
A release publishes two artifacts and deploys nothing:
ghcr.io/ic3software/vtafarm:<version> container image
ghcr.io/ic3software/charts/vtafarm:<version> Helm chart
Production is still updated separately with make deploy. A release puts a
version on the shelf; something else has to take it off.
Chart.yaml holds the only version number:
version: 0.7.0
appVersion: "0.7.0"The two are kept equal and one release bumps both. make release reads
version from this file, so the image tag and the chart version cannot
disagree. Add the release notes to CHANGELOG.md at the same time.
While this is 0.x the values structure may change in any release. Anything that
would make an existing values.yaml behave differently belongs under
Breaking in the changelog.
Docker Desktop running, and both registries logged in — Docker and Helm keep separate credentials, so logging into one does not cover the other:
gh auth token | docker login ghcr.io -u <github-user> --password-stdin
gh auth token | helm registry login ghcr.io -u <github-user> --password-stdinThe gh token needs the write:packages scope:
gh auth refresh -h github.com -s write:packages -s read:packagesRun them in this order. main requires the ✍️ Sign-off status check, which
runs on pull requests, and this repository uses squash merges. Prepare each
release on a branch, merge it, and tag the resulting commit on main. The tag
and the artifacts must describe that same tree.
1. Create a release branch, then write the changelog and bump the version in one commit.
git switch main
git pull --ff-only
git switch -c chore/release-0.7.0
vim CHANGELOG.md # add the new version's entry
vim helm/vtafarm/Chart.yaml # version and appVersion
git add CHANGELOG.md helm/vtafarm/Chart.yaml
git commit -s -m "chore: release 0.7.0"2. Push the branch, open a pull request and wait for its checks.
git push -u origin chore/release-0.7.0Open the pushed branch on GitHub, create a pull request targeting main, and
wait for the ✍️ Sign-off check to pass. Merge it on GitHub with Squash and
merge. Do not create the version tag on the release branch: squash merging
creates a different commit on main.
3. Update main and tag the merged commit.
git switch main
git pull --ff-only
git tag -s v0.7.0 -m "vtafarm 0.7.0"The tag is signed (-s), so GitHub shows it as verified rather than
unverified. This repo signs its commits already; git config tag.gpgsign true
extends that to tags so a plain git tag -a signs too.
The v prefix is used everywhere a person reads the version — the git tag, the
GitHub release, the changelog heading. Chart.yaml and the artifacts it names
stay bare, which is the Helm and OCI convention.
Tag before building. If the build fails, git tag -d v0.7.0 and retry; an
untagged successful release is the worse failure, because nothing points at the
commit the artifacts came from.
4. Build and publish.
make releaseThis first verifies that the working tree is clean and that the signed
v0.7.0 tag points to HEAD. It then runs the complete publication sequence:
docker buildx build --platform linux/amd64 -t ghcr.io/ic3software/vtafarm:0.7.0 --push .
helm package helm/vtafarm -d .charts
helm push .charts/vtafarm-0.7.0.tgz oci://ghcr.io/ic3software/charts
git push origin v0.7.0
# Create the v0.7.0 GitHub release from its CHANGELOG.md section.The GitHub release receives only the v0.7.0 section from CHANGELOG.md; the
Makefile extracts it automatically. The pull request already updated main,
while the final two commands publish the signed tag and its release together.
If image and chart publication succeeds but the tag or GitHub release step fails, retry only that final stage:
make release-githubThat target is safe to rerun. Pushing the same tag is harmless, and it exits successfully when the GitHub release already exists.
--platform linux/amd64 is not optional. The cluster nodes are x86; a release
built on an arm64 machine without it produces an image that fails to start with
exec format error.
helm show chart oci://ghcr.io/ic3software/charts/vtafarm --version 0.7.0
docker manifest inspect ghcr.io/ic3software/vtafarm:0.7.0 | grep architectureThe architecture must be amd64.
docker manifest inspect also lists an unknown/unknown entry. That is the
build provenance attestation buildx attaches by default, not a broken image —
the kubelet selects linux/amd64 and ignores it.
The steps are ordered so that a failure leaves nothing published under a version number that later means something else. Registries treat a pushed tag as immutable: never re-push a version that already exists, bump instead.
| Failed at | Recovery |
|---|---|
| Before the pull request is merged | Fix the release branch, commit with -s, push and wait for the checks again |
After merge, before make release, tag not pushed |
git tag -d v0.7.0; fix through another pull request, then tag the new main commit |
| Image pushed, chart failed | Fix and re-run make release — the image push is idempotent for the same content |
| Image and chart pushed, GitHub publication failed | Run make release-github to retry only the tag and GitHub release |
| Both pushed, then a bug is found | Do not overwrite. Release the fix as the next version |
| Tag already pushed | Leave it. Moving a published tag needs a force push, which this repo does not do |