Skip to content

Latest commit

 

History

History
160 lines (118 loc) · 5.64 KB

release.md

File metadata and controls

160 lines (118 loc) · 5.64 KB

Release

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.

Versioning

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.

Prerequisites

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-stdin

The gh token needs the write:packages scope:

gh auth refresh -h github.com -s write:packages -s read:packages

Steps

Run 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.0

Open 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 release

This 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-github

That 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.

Verifying

helm show chart oci://ghcr.io/ic3software/charts/vtafarm --version 0.7.0
docker manifest inspect ghcr.io/ic3software/vtafarm:0.7.0 | grep architecture

The 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.

When something fails partway

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