Skip to content
CommonLayer
Documentation menu
On this page

ADR-0027: Referrer discovery without the OCI referrers API

Status: Accepted (WP-11). Implemented in crates/commonlayer-registry/src/adapters/oci.rs and mirror.rs.

Context

Signatures, attestations and SBOMs are attached to an image as OCI referrers. The OCI 1.1 referrers API lists them, but CNCF Distribution 3.1.2 answers 404 on it.

Decision

  • Discover referrers through the OCI referrers tag schema (sha256-<hex>, which cosign 3 writes) and cosign's legacy .sig, .att and .sbom tags.
  • The mirror copies referrer manifests byte for byte and writes those referrer tags at the destination, so cosign verify works against the CommonLayer reference without change. Release tags are written only by the promotion step.

Consequences

  • Verified for real with a cosign key-pair signature made at the source registry and verified at the destination (WP-11 mirror test).
  • Attestations stored only through the referrers API of the source registry (for example GitHub's artifact attestations on GHCR, which the template's provenance step produces) are found only if they are also reachable through the tag schema. Whether the provenance produced by actions/attest-build-provenance is discovered and verified by the pipeline has not been tested end to end; see the implementation status.

Amendment, 2026-11-10

  • The publish drill (WP-70g) confirmed the tag-schema path with cosign-made signatures and attestations through a real mirror and promotion. Provenance made by actions/attest-build-provenance with push-to-registry (the template's release workflow) has still not been produced or discovered by the pipeline: that workflow has never run (threat model open item O11).