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.mdputs 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 |
| Licence notices | /licenses in every image (LICENSE and THIRD_PARTY_NOTICES.md), and THIRD_PARTY_NOTICES.md on the GitHub release |
| SBOM and build provenance | beside each image in the registry: an SPDX SBOM as a cosign attestation, and GitHub’s SLSA build provenance |
-
Every image is built for
linux/amd64andlinux/arm64, against Go’s certified FIPS 140-3 module. The gate logsFIPS 140-3 mode: ONat 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.
-
The images and the chart are signed with Sigstore keyless signing by the release workflow, each by digest, from the release after 0.1.0 on (0.1.0 itself is not signed; verify it by the digests in its release notes and the chart’s
values.yaml). Verify an image or the chart with cosign 2.4.2 or later:V=<version> ID="https://github.com/flyyellowjack/yellowjack/.github/workflows/release.yml@refs/tags/v$V" for i in firewall approval console; do cosign verify "ghcr.io/flyyellowjack/yellowjack-$i:$V" \ --certificate-identity "$ID" --certificate-oidc-issuer https://token.actions.githubusercontent.com done cosign verify "ghcr.io/flyyellowjack/charts/yellowjack:$V" \ --certificate-identity "$ID" --certificate-oidc-issuer https://token.actions.githubusercontent.comIt refuses an image signed by any other workflow, repository or tag. The signature is stored beside the image as a separate tag, so a mirror keeps it only if it copies that too:
cosign copydoes; a plain image copy does not. -
Each image carries an SBOM and build provenance, from the release after 0.1.0 on. The SBOM is SPDX, made by syft from the published image, and attached as a cosign attestation signed by the same workflow identity. The provenance is GitHub’s SLSA attestation of the workflow run that built the image. Both are stored beside the image, so the image index a cluster pulls is unchanged. Verify them:
cosign verify-attestation --type spdxjson "ghcr.io/flyyellowjack/yellowjack-firewall:$V" \ --certificate-identity "$ID" --certificate-oidc-issuer https://token.actions.githubusercontent.com gh attestation verify "oci://ghcr.io/flyyellowjack/yellowjack-firewall:$V" -R flyyellowjack/yellowjackcosign verify-attestationprints the SBOM inside a signed envelope;cosign download attestationfetches it without verifying. -
THIRD_PARTY_NOTICES.mdis generated, bygo run ./scripts/thirdparty, from the modules each binary links (go list -depsover every Dockerfile’s build andyj’s platforms), with each licence quoted in full. After anygo.modchange, regenerate it and read the diff: it is what the binaries now ship. A unit test fails until it is current, and stops on a licence it does not recognise, so a new dependency’s terms are read before it ships. -
The
yjbinaries 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 withSHA256SUMS.
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. You need
cosign 2.4.2 or later:
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.
cosign older than 2.4.2 cannot read this signature bundle and fails with bundle does not contain cert for verification, please provide public key. That error comes from the old cosign,
not from a bad release: upgrade cosign and run the same command again. Measured against v0.1.0:
cosign 2.4.0 and 2.4.1 fail this way, and 2.4.2 through 3.0.2 print Verified 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.
When a certificate authority is distrusted
The gate verifies every TLS connection it makes against the CA bundle in the pinned
distroless/static base image, plus FW_UPSTREAM_CA_BUNDLE. Go checks no revocation, so a
compromised CA stays trusted until one of three things changes. In order of speed:
- You, immediately:
FW_UPSTREAM_DISTRUST. List the SHA-256 of each affected key (SPKI) and restart. The SPKI form also covers every cross-sign of the same key.openssl x509 -in ca.pem -noout -pubkey | openssl pkey -pubin -outform der | openssl dgst -sha256prints it. - A Go release. When Go blocks the keys in
crypto/x509itself, as Go 1.26.10 and 1.27.3 did for the eight eMudhra intermediates (CVE-2026-111943), we rebuild with that toolchain and cut a patch release. The block applies even to an operator’s own roots. - A base-image re-pin. When Debian’s
ca-certificatesdrops a root, we re-pindistroless/staticin every Dockerfile, runsh scripts/base-image-roots.sh, and review the diff ofdeploy/base-image-roots.txt: each line removed is a root the gate stops trusting, each line added one it starts trusting. The test that pins the record to the Dockerfiles’ digest fails until that is done, so a re-pin cannot change what the gate trusts unreviewed. A patch release follows.
The eMudhra event (October 2026), for the record: the eight compromised intermediates were
issued under emSign Root TLS CA - G3 and emSign Root CS CA - G3, neither of which is in our
base image, and cross-signed by AAA Certificate Services, which is. Go 1.26.10, which every
0.1.0 image is built with, rejects chains through all eight keys. The four emSign roots our base
image does trust (C1, G1, ECC C3, ECC G3) did not issue them.
Cutting a release (maintainers)
- Move the
CHANGELOG.mdentries under## [<version>] - <date>and setversionandappVersionindeploy/helm/yellowjack/Chart.yamlto the same version. - Push the tag
v<version>on that commit. .github/workflows/release.ymlrunsscripts/release.sh. It refuses a tag that disagrees with the changelog or the chart, buildsyjfor the five platforms and signsSHA256SUMS(and verifies that signature as a user would), runs the unit tests, builds and pushes the three images, pins them in the chart, and pushes the chart. A separatesignjob then signs the three images and the chart by digest, verifies each signature as a user would, and only then creates the GitHub release with the chart and theyjfiles attached. Signing needs no stored key or secret: theyjandsignjobs’id-token: writepermission is what lets them get a certificate, and neither job runs the unit tests.
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.