Release Compatibility & Artifact Security Policy

MCP Hangar ships as independently versioned artifacts (see Releases & Artifacts for where each one lives and how to install it). Because they release on separate SemVer lines per ADR-009, "which versions work together" is answered by the compatibility matrix below, not by a shared version number. This page is that matrix plus the artifact-security policy that governs how the images and charts are published and verified.

Status: released, signed, and pinned — the published charts carry their fixes and chart tags are now immutable (mcp-hangar/helm-charts#36, closed; fixed by the fail-safe publish guard #37). As of 2026-07-31 every lane has a published, public, cosign-signed, digest-verified artifact with SBOM/provenance (see Released artifacts): core image 2.0.0, operator 0.15.0, and both Helm charts. The 2.x line went stable on 2026-07-31 and is now the reference row below; it was previously excluded here as a release candidate, which this page kept asserting after it stopped being true. Image signing + SBOM (mcp-hangar/mcp-hangar#467) is done.

Live cluster testing found defects that made a default helm install fail outright — a config key the 1.5 server rejects, flags the operator image does not accept, CRDs that do not match the kinds the image watches, and a CRD the API server refuses. Those are fixed, and the fixes are present in the currently-published charts: verified by pulling charts/mcp-hangar 0.13.4 and charts/mcp-hangar-operator 0.12.3 from GHCR and inspecting their contents, not by inference. The helm-charts repo also had no chart lint/render/install CI at all — that gate now exists, which is why this class of defect will not ship again.

Chart tags are immutable (mcp-hangar/helm-charts#36, closed). The publish guard probes with crane manifest and skips any version already in the registry (#37), so a released chart tag's content never changes after publication — the digests recorded in Released artifacts are stable pins.

Kubernetes-range validation is done (see the matrix). Independent release is still not formally declared supported: the remaining Verification status items are human-gated — a named CODEOWNERS owner and security/owner sign-off.

Ownership and update procedure

• Owner: the release maintainers (the #453 / ADR-009 owners). The matrix has a single named owner recorded in the repository CODEOWNERS for this file; changes require that owner's review.
• Update trigger: every artifact release updates this matrix in the same PR, or in an immediate follow-up PR, that cuts the release. A release whose compatibility is not reflected here is incomplete.
• Cadence: the matrix is reviewed at least once per core minor release even if satellites did not move, to re-confirm the Kubernetes support window.

Compatibility matrix

Each row is a supported combination. An artifact version absent from this table is not a supported combination — it may work, but it is not covered.

charts/mcp-hangar 0.13.7 carries appVersion: 2.0.0, and image.tag defaults to appVersion, so a plain helm install of it pulls the 2.0.0 image — verified with helm show chart against the registry. 0.13.6 and earlier carry appVersion: 1.6.2; pin the chart version, not just the image tag, if you are staying on the closed line.

Rules for reading and extending the matrix:

• Core is the reference axis: every supported combination pins a concrete core minor (v2.1.1 is the current published core; 1.6.x is closed and receives no fixes, including the approval-authorization fix released in 2.0.0).
• Operator / Helm columns carry the released version; the verified digests are in Released artifacts below. Both lanes have landed (mcp-hangar-operator#26, helm-charts#7) and the Kubernetes range is now validated. The row is still not formally a supported combination until the owners sign off (see Verification status).
• Kubernetes records the tested server range for combinations that include the operator or a chart. The declared >=1.25 floor is test-confirmed: on a real v1.25.16 control plane both charts install, the operator's CRDs reach Established, an MCPServer reconciles into a child resource with correct owner references, and the core gateway serves /health/ready 200. The same charts run on v1.36.1. Every apiVersion the charts render (autoscaling/v2, policy/v1, networking.k8s.io/v1, admissionregistration.k8s.io/v1, apiextensions.k8s.io/v1) has been GA since v1.16--v1.23, so nothing in them is version-fragile inside that window. Validated against the charts on helm-charts main, whose content is what the published tags currently serve (see Status and mcp-hangar/helm-charts#36).
• SemVer boundaries: a change that breaks a documented combination is a MAJOR bump of the artifact that changed. Adding a newly-tested combination is a MINOR/docs change to this matrix, not a version bump of any artifact.

Released artifacts (verified)

Digests for every published artifact, confirmed by anonymous pull. All are public; images and charts marked signed carry a keyless cosign signature and an SBOM/provenance attestation.

Image and chart digests are pins. The publish guard (mcp-hangar/helm-charts#37) skips re-push of any already-published version, so a released tag's digest is stable — verified de-facto: the earlier-recorded 0.13.2 chart digest is unchanged today. Read once, pin by digest.

Superseded (do not use): operator image 0.12.0/0.12.1 (unsigned), and the mcp-hangar chart 0.12.0/0.13.0/0.13.1 (the 0.12.0 chart pointed at a non-existent core image tag; 0.13.1 predates the install fixes and still declares appVersion 1.4.0). The core image is versioned on its own 1.x line (matching PyPI core); its release workflow already cosign-signs and attaches build provenance.

CRD upgrade and rollback policy

The operator owns the CRDs; this policy binds the operator lane.

• Additive within a major. New CRD fields are optional with safe defaults and are introduced in a MINOR operator release. Existing objects remain valid without edits.
• Breaking changes require a new CRD version + conversion. A field removal, a type change, or a semantics change ships under a new CRD API version (v1alpha2, v1beta1, …) with a conversion path (webhook or a documented manual migration). The old version is served for at least one operator MINOR before it is deprecated, and deprecation is announced in the release notes.
• Rollback constraint. Downgrading the operator is supported only within the same served CRD version. Rolling back across a CRD-version bump requires the documented conversion in reverse and is not guaranteed lossless — objects created with new-version-only fields may not round-trip. Each operator release states its safe rollback floor.
• Stored version. Only one CRD version is marked storage: true at a time; bumping it is itself a breaking change subject to the rule above.

Artifact security policy (GHCR)

All images and charts publish to the org GHCR namespace (ghcr.io/mcp-hangar/…). The following posture is the target for #453 verification against the live registry.

Consumer verification

Pull by digest and verify the signature before deploying:

# Resolve a tag to an immutable digest, then pin it.
docker buildx imagetools inspect ghcr.io/mcp-hangar/mcp-hangar-operator:<version>

# Verify the keyless signature (identity = the publishing workflow).
cosign verify ghcr.io/mcp-hangar/mcp-hangar-operator@sha256:<digest> \
  --certificate-identity-regexp 'https://github.com/mcp-hangar/.+' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Charts are verified the same way against oci://ghcr.io/mcp-hangar/charts/<chart>.

Active (2026-07-15): every release workflow signs keyless with cosign and attaches SBOM/provenance — the operator and chart lanes (mcp-hangar/mcp-hangar#467) and the core image lane (which already signed and attached provenance) — so the recipe above succeeds against every artifact in Released artifacts.

Verification status

The policy above is declared supported only when every box is checked. All release lanes are published and signed and the Kubernetes range is now validated; the remaining boxes are the human-gated criteria from #453 (a named owner and security sign-off) plus a chart re-release.

• Matrix has a named owner in CODEOWNERS and the update procedure is in effect.
• First operator image + manifest released with a verified digest and install instructions (mcp-hangar-operator#26) — signed 0.12.2, public, sha256:91f8fea3…c34ce42f, install.yaml attached to the release.
• First charts published with verified digests (helm-charts#7) — both charts public and signed: mcp-hangar 0.13.1, mcp-hangar-operator 0.12.1 (digests in Released artifacts). The current core chart is 0.13.4; 0.13.1 predates the install fixes and is superseded.
• The published charts install: the fixes found by live testing are present in charts/mcp-hangar 0.13.4 and charts/mcp-hangar-operator 0.12.3 as served today (verified by pulling and inspecting them).
• Chart releases are immutable — the publish guard skips re-push of an already-published version (mcp-hangar/helm-charts#36, closed; fixed by the crane manifest probe in #37), so a released chart tag's digest is a stable pin.
• Kubernetes support range validated (1.25 -- 1.36) against a real control plane at the declared floor v1.25.16 and at v1.36.1: charts install, CRDs reach Established, an MCPServer reconciles into a child with correct owner references, and the gateway serves /health/ready 200. Validated against the fixed charts on main.
• (Agent image release lane retired along with the discontinued cluster agent product; it never reached general availability and is no longer part of this matrix or the verification checklist.)
• GHCR signing + SBOM/provenance (mcp-hangar/mcp-hangar#467) — the core image, operator, and all charts carry a keyless cosign signature + attestation, confirmed present in the registry; public visibility confirmed for all artifacts. (Immutability/retention follow GHCR defaults.)
• CRD rollback / compatibility limits validated against a real operator release.
• Security policy approved by the release and security owners.

References

• ADR-009 — Independent Release Topology
• ADR-004 — Digest Pinning
• Releases & Artifacts
• Release Operations Runbook
• Tracking issue: mcp-hangar/mcp-hangar#453; parent #410.