← All docs

Releases

From docs/RELEASING.md at v0.2.0 ·View the source on GitHub

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

  • 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.com

    It 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 copy does; 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/yellowjack

    cosign verify-attestation prints the SBOM inside a signed envelope; cosign download attestation fetches it without verifying.

  • THIRD_PARTY_NOTICES.md is generated, by go run ./scripts/thirdparty, from the modules each binary links (go list -deps over every Dockerfile’s build and yj’s platforms), with each licence quoted in full. After any go.mod change, 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 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. 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:

  1. 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 -sha256 prints it.
  2. A Go release. When Go blocks the keys in crypto/x509 itself, 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.
  3. A base-image re-pin. When Debian’s ca-certificates drops a root, we re-pin distroless/static in every Dockerfile, run sh scripts/base-image-roots.sh, and review the diff of deploy/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)

  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, and pushes the chart. A separate sign job 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 the yj files attached. Signing needs no stored key or secret: the yj and sign jobs’ id-token: write permission 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.