OCI Referrers: Discover and Promote the Artifact Graph, Not Just the Image

Copying an image digest to a production registry does not automatically prove that its SBOMs, signatures, or provenance are discoverable there. OCI referrers add a reverse-discovery mechanism: a manifest can name another manifest as its subject, and a client can ask the registry which artifacts refer to that subject. Promotion therefore involves a graph of related manifests, not merely the image’s config and layers.

This article follows OCI Distribution Specification 1.1.0 and OCI Image Specification 1.1.0. The command examples use the ORAS 1.3 documentation reviewed on October 11, 2026. ORAS marks discovery and recursive-copy features as preview or experimental; pin the actual client version in automation and test its behavior against both registry endpoints.

Model direction and repository scope correctly

An OCI manifest’s optional subject descriptor establishes a weak association with another manifest. The referring artifact carries the forward link; the Referrers API supplies the reverse lookup. This relationship differs from an image manifest’s config and layer descriptors, which describe the content it depends on.

The reverse-discovery endpoint is:

GET /v2/<repository>/referrers/<subject-digest>

Results are descriptors for referring manifests or indexes in that same repository namespace. A digest is content identity, but the lookup is also repository-scoped. Discovering attachments in staging/app says nothing about their discoverability in production/app, even when the subject’s digest is identical.

This distinction also separates copying bytes from registering relationships. An artifact stored elsewhere is not automatically included in this repository’s reverse lookup. A production release record should name the registry, repository, subject digest, and required referrer digests together. The digest alone does not encode the location where the association can be found.

Distinguish a valid empty list from unsupported discovery

For a found repository and a valid request, a registry supporting the OCI 1.1 Referrers API returns HTTP 200 with an OCI image index. Its manifests array can be empty. A valid empty result is therefore not an API failure and should not trigger an unsupported-endpoint fallback.

The 1.1 specification requires fallback to the referrers tag schema when the API returns HTTP 404. The schema stores the reverse index under a tag derived from the subject digest’s algorithm and digest component, such as a sha256- prefix followed by the hexadecimal digest. If that fallback does not return a valid image index, the specification’s discovery behavior permits treating the subject as having no referrers.

Keep release policy stricter than discovery. If production requires a verified SBOM and signature, “no referrers discovered” fails that policy even when the registry protocol was handled correctly. Authentication failures, forbidden access, rate limits, invalid digests, and server errors should retain their own diagnosis; treating all non-200 responses as absence would hide operational failures.

Pagination and filtering are correctness requirements

The API can paginate a result that does not fit in one index. Its response includes a Link header with rel="next", and each page supplies another index with descriptors. A custom discovery client must follow the continuation chain before claiming to have collected the complete direct-referrer set.

Bound that traversal by time, response size, and a maximum number of pages. Preserve the request context, detect repeated continuation links, and apply an explicit origin policy before sending credentials to a continuation URL. Those are client-engineering controls around the protocol, not additional OCI header requirements.

Artifact-type filtering is recommended for registries, not universally guaranteed. When the requested filter is applied, the response must include OCI-Filters-Applied: artifactType. A client should inspect the applied-filter header and validate returned descriptor types instead of assuming that a query parameter proved server-side filtering happened.

For an audit, an unfiltered inventory is often the better baseline. A filtered signature lookup can satisfy one question while omitting required attestations or unknown artifact types. Discovery gives candidates; their artifactType, annotations, and subject relationship are not themselves authorization or cryptographic verification.

Collect a bounded source inventory

The following shell template assumes OCI_SUBJECT has been set to a real repository reference pinned by manifest digest, with registry authentication already configured:

: "${OCI_SUBJECT:?Set a real repository@sha256:digest reference}"
oras version
oras discover --format json --depth 1 "$OCI_SUBJECT"

The documented --depth 1 option limits the displayed result to direct referrers. Without that limit, ORAS can display further referrer levels. Record whether the inventory is direct or transitive; a signature that refers to an SBOM is a different edge from a signature that refers directly to the image.

For a controlled compatibility test, the documented mode flags allow explicit selection:

oras discover --distribution-spec v1.1-referrers-api "$OCI_SUBJECT"
oras discover --distribution-spec v1.1-referrers-tag "$OCI_SUBJECT"

These are test commands, not a claim that both modes should show identical data in every deployed registry. Legacy tag indexes may be incomplete, and registry upgrade behavior matters. Record the discovery method, authenticated identity, time, and inventory before interpreting a difference.

Promote with recursive copy, then verify independently

ORAS documents recursive copy as copying an artifact and its referrer artifacts. Use a digest-pinned source and a controlled destination tag after establishing the required source inventory:

: "${OCI_DESTINATION:?Set a staging repository:tag destination}"
oras cp --recursive "$OCI_SUBJECT" "$OCI_DESTINATION"

The destination in this template is a release-staging reference, not a recommendation to overwrite a live production tag during an unverified copy. The documentation also exposes separate source and destination distribution-mode flags, allowing a test involving a native API on one side and the fallback tag mechanism on the other.

Do not equate recursive referrer copying with platform selection. Copying an image index ordinarily includes its manifests; asking for one platform changes the artifact-selection question. If the release contract is the original multi-platform subject digest and its evidence graph, verify that exact subject rather than quietly promoting a selected child manifest.

After copying, rediscover from the destination repository. Fetch the required referring manifests and verify their content digests, subject descriptors, and policy-relevant payloads. Perform signature or attestation verification using the expected identities and trust configuration. A matching descriptor count is insufficient: two different referrers can produce the same count, and an attacker-controlled attachment can name the correct subject.

The subject is immutable; its referrer set is not

A digest-pinned subject does not freeze all future associations. Another writer can add an attestation while promotion is running. The tag-schema fallback also requires clients to maintain an index, and concurrent updates can race or lose entries. The specification identifies that risk and allows conditional pushes where the registry supports them.

Establish a release cutoff or an explicitly approved referrer set. Record which evidence was reviewed and compare that set at the destination. If the source set changes during copying, decide whether the change belongs in this release instead of allowing an uncontrolled graph expansion to become implicit approval.

Retention and deletion deserve similar testing. The weak association is not a universal promise that every garbage collector retains all evidence forever. Test the registry’s retention policy, relevant deletion behavior, and rediscovery after the period your audit requires. Preserve independently archived release evidence when the registry cannot provide the necessary retention contract.

Diagnose promotion failures by the missing boundary

When an attachment is absent, separate source discovery, source read authorization, recursive traversal, destination write authorization, destination relationship discovery, and cryptographic verification. A successful image pull proves only that the image’s content path works. It does not prove that a referrer index was maintained or that a verifier accepts the attached evidence.

Use a scratch repository to test a valid empty list, API fallback, multiple pages, unapplied artifact filtering, a referrer-of-a-referrer, and concurrent attachment changes. Capture actual responses and client versions; the templates above intentionally provide no invented runtime output.

Promotion is accepted when the intended subject and required evidence graph are present, discoverable in the destination’s namespace, content-verified, and approved by the release policy. OCI discovery solves finding associations. The operator still owns completeness, trust, timing, and the decision that those associations are sufficient for production.

Related:

Sources: