feat(release): publish hardened, scanned and signed OCI image to GHCR - #145

Add `What a release contains` and `Container image tags` to the release process
page: the full artifact set (Maven coordinates, the GHCR image, its SBOM and its
Cosign signature), the Helm chart and Compose sample named as explicitly deferred,
and the rule that the image version is the Maven version — enforced by the publish
job's version-identity assertion rather than by convention.

Record the build-authority inversion (test-which-builds, then push-that-digest) and
why it exists, so a later reader does not "correct" it back into a second docker
build or a skip-guard on integration-tests/pom.xml.

State the two-tag scheme: `<version>` for humans and `sha-<commit>` for immutable
provenance, where `<commit>` is the full 40-character SHA of the commit the release
tag points at, not the dispatching main HEAD. No floating `:latest` at pre-1.0, with
the reason.

Add the one-time post-first-release action to the checklist: a GHCR package created
by a GITHUB_TOKEN push is private by default and the in-workflow smoke cannot detect
it.

The two `Why …` sections recording the 2026-07-12 accidental release and the
merge-order rule are untouched.

Co-Authored-By: Claude <noreply@anthropic.com>

…ase workflow

Add one dependent sibling job, publish-image, needs: [release]. The trigger is
untouched: release.yml stays workflow_dispatch-only and the 2026-07-12 comment
recording the accidental Maven Central release stays verbatim. The release job,
its uses: pin and its secrets: block are unchanged.

The job re-reads the released version from .github/project.yml with the same
pinned read-project-config action the release job used, because
reusable-maven-release.yml declares no on.workflow_call.outputs block and
needs.release.outputs.released-version would silently evaluate to the empty
string. It then checks out the release tag — never the dispatching ref — and
asserts the checked-out project.version equals that version before anything is
built or pushed.

The integration-test suite is the one and only image build in the lane: its
pre-integration-test binding already runs docker compose build, so
test-which-builds then push-that-digest makes "push exactly what was tested" true
by construction. The image is addressed by content-derived image ID between build
and push, and by registry manifest digest thereafter.

Both release tags are pushed (<version> and sha-<release-tag-commit>) against a
hardcoded lowercase registry path, the pushed digest is resolved once and asserted
unique, and the published artifact is smoked by digest: pulled image ID equals the
tested ID (the load-bearing assertion), the version label matches, and the
container becomes live over its HTTPS management interface.

Co-Authored-By: Claude <noreply@anthropic.com>

…d emit an SBOM

Insert two steps into publish-image, between the image-ID resolution and the GHCR
login so the gate provably precedes any registry write.

anchore/sbom-action emits SPDX JSON for the tested image and retains it as a
workflow artifact named for the released version. It is pinned by SHA with a
version comment, like every other action in this repository, and
upload-release-assets is off because the job holds only contents: read.

aquasecurity/trivy-action scans the same image ID with severity HIGH,CRITICAL and
exit-code 1. A finding at either severity fails the job before docker login runs.
The threshold is stricter than a CRITICAL-only gate on purpose and the workflow
says why.

Two comments record what the file would otherwise not tell a future reader: the
scan's real coverage — the image is the pinned distroless base plus one static
native executable and carries no jars, so this is in substance a base-OS-package
scan and a clean result is not a clean dependency tree — and the pinned
attestation posture, namely that the lane must not switch to
docker buildx build --push, whose default attestations would wrap the push in a
manifest list and change what the pull-by-digest smoke pulls and what Cosign signs.

Co-Authored-By: Claude <noreply@anthropic.com>

…orkflow

Add a second job, supply-chain-scan, to maven.yml. It declares no needs:, so it
neither delays nor is delayed by the existing build job, and it runs on the
workflow's existing pull_request / push / merge_group triggers with no trigger
change.

It scans the pinned base image — read by digest out of Dockerfile.native rather
than restated, with a guard that fails the step if the base ever stops being
digest-pinned — and the repository filesystem, which is what actually surfaces
Java dependency CVEs. It emits an SPDX SBOM for the base image, a readable report
into the job summary, and SARIF as an artifact.

No pull request gains a native image build: scanning the base plus the filesystem
gets the early-warning signal at roughly a minute and zero builds, and the release
image is that same base plus one static binary carrying no package metadata.

Every Trivy step sets exit-code: 0, so a vulnerability finding never fails the PR.
continue-on-error is deliberately not used — it would also mask a genuine tool or
network failure, whereas exit-code: 0 suppresses only the vulnerability verdict.

A comment names the other lane and the distinct purpose of each, so the two are
not later "simplified" as redundant.

Co-Authored-By: Claude <noreply@anthropic.com>

Append sigstore/cosign-installer and a `cosign sign --yes` over the resolved
registry digest to publish-image, after the push and after the smoke, so the
signed artifact is provably the tested and published one. Signing is by digest,
never by tag: a tag is a mutable pointer and signing one signs nothing durable.

No new job, no new permission — id-token: write is already on the job — no key
material, no COSIGN_PRIVATE_KEY and no new secret. SLSA provenance and any further
attestation stay out of scope.

A comment records the two values a consumer needs to verify the signature. They
are derived from this job's identity and change silently if the workflow file is
renamed or a release is dispatched from a non-main ref, so recording them here is
what keeps them from drifting from the copy the operator guide publishes.

Also route the GHCR credentials through the step environment instead of
interpolating `${{ }}` into the run block, matching the treatment already used for
every other value in this job.

Co-Authored-By: Claude <noreply@anthropic.com>

Add doc/user/container-image.adoc: which tag to use and why no `:latest` exists,
a `docker run` that reflects what the artifact genuinely requires rather than an
idealised one-liner — the mandatory mounted configuration directory (the container
fails fast without one because sheriff.config.dir is relative), the
deployment-supplied certificate material for both listeners, the published ports,
and the QUARKUS_HTTP_SSL_PORT move that tls.passthrough_sni forces.

State honestly what the SBOM and the scan cover: the release fails on a HIGH or
CRITICAL finding against the exact published image, but that image is the pinned
distroless base plus one static executable with no jars, so an operator who needs
a Java dependency inventory reads the SBOM rather than inferring it from a clean
scan.

Give the complete `cosign verify` recipe with both mandatory flags, explain what
each one pins and why omitting either makes the verification meaningless, and
state that a non-zero exit means the artifact must not be deployed. The identity
and issuer strings are character-identical to the comment in release.yml.

Add the corresponding row to the operator-guide index; the layer's scope statement
already named the production container image, so no scope text changes.

Co-Authored-By: Claude <noreply@anthropic.com>

Add doc/resources/diagrams/release-publish-flow.svg, a two-track flow diagram
authored to the existing flow type: the release lane (dispatch, Maven release,
release-tag checkout with the version assertion, the IT suite that is the one and
only image build, the SBOM and gating scan, tag and push, pull-by-digest smoke,
Cosign sign) and the independent non-gating pull-request lane. The two tracks
deliberately do not converge — that is the diagram's load-bearing idea, and the
footer caption says so.

Shape carries the stage role: taller process shapes for the work that takes time,
a diamond for the scan gate, event shapes for the moments. Theme-neutral strategy
A with the single #6e7681 token, matching the five existing diagrams, and
viewBox width 1160 matching request-pipeline.svg so the two flow diagrams render
at the same scale.

Rendered against #ffffff and #0d1117 and both PNGs read back; the Step 4 checklist
passes on both backgrounds. The rendered page carries exactly one reference to the
SVG.

Embed it in the `What a release contains` section with alt text. Every section the
page already had survives unchanged.

Co-Authored-By: Claude <noreply@anthropic.com>

Add a `Container Image (three-layer topic)` row to the design index, following the
shape the existing TLS Edge row establishes. The design index is where a reader
discovers that a topic exists across all three layers, so this is the reference
layer's real, non-vacuous edit.

The row itself carries the reference-layer statement: the image is a packaging of
the same binary the architecture document already describes, so it adds no runtime
component, no request-lifecycle stage and no gateway.yaml key. Neither
doc/architecture.adoc nor doc/configuration.adoc has a surface for it, and both are
genuinely unchanged by this plan rather than skipped.

Co-Authored-By: Claude <noreply@anthropic.com>

…view

Pre-submission self-review caught claims the artifact does not support:

- The native executable is NOT statically linked. quarkus.native.additional-build-args
  configures no --static and no --libc=musl, which is exactly why the base is the
  glibc-bearing quarkus-distroless-image rather than scratch. Corrected in both
  workflow comments and the three doc occurrences. The load-bearing property is
  unchanged and in fact stronger: the layer carries no package metadata and no jars.
- container-image.adoc told operators to read the SBOM for a Java dependency
  inventory. The SBOM catalogues the same jar-free image the scan covers, so it
  structurally cannot contain one; the very next sentence already routed the reader
  elsewhere. Java dependency CVEs come from the fs-scan, Sonar and Dependabot lanes.
- The SBOM is a workflow-run artifact (upload-release-assets: false), not something
  "published" with the release.
- cosign >= 2.0 refuses keyless verification outright without --certificate-identity
  and --certificate-oidc-issuer; it does not "accept any Sigstore identity".
- doc/development/README.adoc was the one layer index the plan missed while
  release-process.adoc gained 97 lines.

The two cosign verify strings in release.yml and container-image.adoc were confirmed
character-identical by exact literal match, not by eye.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RgENQAQcLGAWiLFfM414Yx

Security audit of the plan footprint (persona-security-expert + oci-security):

- trivy-action was pinned to a9c7b0f0, which is the ANNOTATED TAG OBJECT for
  v0.36.0, not a commit. GitHub's ref API peels it so the workflow ran, but
  Dependabot's github-actions ecosystem tracks commit SHAs — a scanning action
  pinned in tag-object form silently stops receiving bumps. Repinned to the
  commit ed142fd0 in all five occurrences.
- The operator cosign recipe verified a TAG. The signature is over the digest,
  so verifying a tag makes cosign resolve it independently of the deployment's
  own resolution, leaving a repoint window between the two — contradicting the
  doc's own "a digest cannot be repointed" note. The recipe now resolves the
  digest and passes that reference to both cosign verify and the manifest.
- Operator docker run recipe gains --cap-drop=ALL --security-opt=no-new-privileges
  (oci-security D01/D04), safe by construction: nonroot, unprivileged ports,
  distroless so no setuid binary exists.

Audit confirmed and left unchanged: release.yml remains workflow_dispatch-only
and its diff is strictly additive; no ${{ }} interpolation survives in any run
body; per-job permissions are least-privilege; Cosign is genuinely keyless with
no key material; the .dockerignore allowlist admits only target/*-runner.

Two findings filed rather than fixed: the smoke step's pull-by-digest is not a
real registry round-trip (the image stays resident under its RepoDigest, so the
identity assertion cannot fail) and publish-image runs harden-runner in audit
mode while holding packages+id-token write. Both need a real dispatched release
to fix safely.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RgENQAQcLGAWiLFfM414Yx