Releases

Versions

Releases are tagged vMAJOR.MINOR.PATCH and follow Semantic Versioning. While the major version is 0, a minor release may change behaviour; CHANGELOG.md says what changed and what an operator has to do about it.

A patch release carries bug and security fixes only. It adds no configuration and changes no behaviour a default deployment would notice, so moving from 0.1.0 to 0.1.1 is always safe to do without reading more than the changelog entry.

Which releases get fixes

A release line is a minor version: 0.1.x, 0.2.x. While the major version is 0, a new minor version starts a new line.

• The newest line gets every fix.
• The line before it gets patch releases for 3 months after the newer line’s first release. Those patch releases carry breaking bugs and serious security vulnerabilities only: a failure a default deployment hits that has no reasonable workaround, or a vulnerability that can deliver a blocked package or leak what passes through (the classes SECURITY.md puts in scope). Not every bug gets a patch on an older line.
• Older lines get nothing. Upgrade to a supported line to receive a fix.

Plan to update monthly. A patch release is always safe to take on its changelog entry alone (see above), so a monthly update keeps a deployment on the newest line and inside this window with no effort beyond reading CHANGELOG.md.

What a release publishes

A tag publishes, from the tagged commit and nothing else:

What	Where
The gate	ghcr.io/flyyellowjack/yellowjack-firewall:<version>
The control plane	ghcr.io/flyyellowjack/yellowjack-approval:<version>
The console	ghcr.io/flyyellowjack/yellowjack-console:<version>
The Helm chart	oci://ghcr.io/flyyellowjack/charts/yellowjack, chart version = <version>
The yj CLI	the GitHub release: yj-linux-amd64, yj-linux-arm64, yj-darwin-amd64, yj-darwin-arm64, yj-windows-amd64.exe, with SHA256SUMS and its signature SHA256SUMS.sigstore.json
Release notes	the GitHub release, carrying the CHANGELOG.md section and each image’s digest

• Every image is built for linux/amd64 and linux/arm64, against Go’s certified FIPS 140-3 module. The gate logs FIPS 140-3 mode: ON at startup (docs/SETUP.md, “FIPS 140-3 mode”).
• The published chart pins each image by digest as well as tag, so a cluster pulls exactly the bytes that were published even if a tag is later moved. The chart in this repository (deploy/helm/yellowjack) builds from source instead; the release job rewrites the image references in the packaged copy only.
• The optional scoring images (scheduler and scanner) are not published. The chart does not deploy them; build them from source if you run local scoring.
• Images are not signed yet. Verify by digest: the digests in the release notes and in the chart’s values.yaml must match what your registry mirror holds.
• The yj binaries are static (no cgo) and built reproducibly: the same tag and Go version give the same bytes, so you can rebuild one and compare it with SHA256SUMS.

Install a release:

helm install yellowjack oci://ghcr.io/flyyellowjack/charts/yellowjack --version <version>

Verifying yj

SHA256SUMS lists the five binaries. It is signed with Sigstore keyless signing: at release time the workflow receives a short-lived certificate naming it, .github/workflows/release.yml in flyyellowjack/yellowjack at the release tag, and the signature is recorded in Sigstore’s public transparency log. There is no long-lived key to leak or rotate. Check the signature first, then the binary against the list:

V=<version> P=linux-amd64     # or linux-arm64, darwin-arm64, darwin-amd64
cosign verify-blob --bundle SHA256SUMS.sigstore.json \
  --certificate-identity "https://github.com/flyyellowjack/yellowjack/.github/workflows/release.yml@refs/tags/v$V" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com SHA256SUMS
grep " yj-$P\$" SHA256SUMS | sha256sum -c -     # macOS: shasum -a 256 -c

On Windows (PowerShell), the same cosign verify-blob command, then compare the hash with the yj-windows-amd64.exe line of SHA256SUMS:

(Get-FileHash yj-windows-amd64.exe -Algorithm SHA256).Hash.ToLower()

cosign verify-blob prints Verified OK and exits 0, and refuses a SHA256SUMS that was changed after signing, or one signed by any other workflow, repository or tag. sha256sum -c prints yj-<platform>: OK.

What this proves: the file list was produced by this repository’s release workflow when it ran for that tag, and the binary you hold is the one in the list. What it does not prove: that the tagged source is free of defects, or that GitHub’s runner was not compromised; the certificate trusts GitHub to say which workflow ran. A reproducible build is the check that does not depend on GitHub: build yj from the tag with the same Go version (sh scripts/release.sh yj v<version>) and compare the hashes.

Cutting a release (maintainers)

1. Move the CHANGELOG.md entries under ## [<version>] - <date> and set version and appVersion in deploy/helm/yellowjack/Chart.yaml to the same version.
2. Push the tag v<version> on that commit.
3. .github/workflows/release.yml runs scripts/release.sh. It refuses a tag that disagrees with the changelog or the chart, builds yj for the five platforms and signs SHA256SUMS (and verifies that signature as a user would), runs the unit tests, builds and pushes the three images, pins them in the chart, pushes the chart, and creates the GitHub release with the chart and the yj files attached. Signing needs no stored key or secret: the yj job’s id-token: write permission is what lets it get a certificate.

scripts/release.sh is all the release does, so it can be rehearsed first against a local registry (REGISTRY=localhost:5000/test INSECURE=1). scripts/release.sh yj v<version> builds the yj files into release-out/yj with no registry at all; only the signature needs the workflow. scripts/release_test.sh tests the parts that decide what gets published: the tag grammar, the changelog and chart agreement, the release notes, the digest pinning, and that the yj build yields exactly the five binaries, each for the platform its name says and each listed in SHA256SUMS.