stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
6e00a48e00da3b2cfbd976a53254275fa63583a6
git.stella-ops.org/docs-archived/product/advisories/2026-02-19-oci-referrers-api-registry-compatibility.md
master b5829dce5c archive audit attempts
2026-02-19 22:07:11 +02:00

6.4 KiB
Raw Blame History

Advisory: OCI Referrers API Registry Compatibility (2026-02-19)

Status: Archived (no implementation gaps) Date received: 2026-02-19 Archived: 2026-02-19

Summary

Advisory covering the fragmented state of OCI Referrers API support across major container registries (GHCR, ECR, Google Artifact Registry, Quay, Harbor, GitLab, Docker Hub) and its impact on supply-chain artifact discovery workflows.

Key points from advisory

  • GHCR: No OCI referrers API endpoint; requires tag-based fallback or GitHub Attestations API
  • ECR: Full OCI Distribution 1.1 support including referrers; lifecycle/GC rules must include referrer artifacts
  • Google Artifact Registry: Exposes an attachments model (gcloud artifacts attachments list) alongside standard OCI; some features in public preview
  • Quay/Quay.io: OCI Referrers API announced; self-hosted deployments may require admin toggles
  • Harbor: API-level support in 2.0+; UI may display cosign/SBOM referrers as "UNKNOWN" in v2.15+
  • GitLab Container Registry: Stores OCI artifacts with subject field but does not expose referrers endpoint
  • Spec nuance: OCI Distribution 1.1 requires runtime detection and fallback to tag-by-digest conventions

Assessment

No implementation gaps found. Stella Ops already comprehensively handles the scenarios described:

  1. Native-first with tag-based fallback: OciReferrerDiscovery.cs, OciReferrerFallback.cs in ExportCenter
  2. Runtime capability probing: ProbeRegistryCapabilitiesAsync() detects OCI 1.1 via distribution headers
  3. Registry compatibility matrix: docs/modules/export-center/registry-compatibility.md covers 12+ registry types
  4. Per-registry handling: GHCR (fallback), ECR (native), GAR (native), Harbor 1.x/2.0+ (split), Quay (partial+fallback)
  5. Cosign interoperability: Full DSSE/cosign-compatible manifests and annotations
  6. No external ORAS dependency: Implements OCI Distribution Spec directly
  7. Doctor health checks: RegistryReferrersApiCheck.cs, RegistryCapabilityProbeCheck.cs
  8. Operational runbooks: docs/runbooks/registry-compatibility.md, docs/runbooks/registry-referrer-troubleshooting.md

Documentation updates applied

Minor polish applied before archiving:

  1. Added GitLab Container Registry to compatibility matrix, troubleshooting runbook, and quick-reference runbook
  2. Refined Google Artifact Registry notes: documented attachments model as alternative UX alongside standard OCI API
  3. Added Harbor UI classification caveat: UI may show referrers as "UNKNOWN" in v2.15+; does not affect API discovery
  4. Added Quay admin toggle note: self-hosted deployments may need feature flags enabled for referrers API
  5. Added troubleshooting entries: Harbor UI "UNKNOWN" issue and Quay inconsistent referrers sections added to runbook

Files updated

  • docs/modules/export-center/registry-compatibility.md
  • docs/runbooks/registry-compatibility.md
  • docs/runbooks/registry-referrer-troubleshooting.md

Original advisory content

OCI Referrers API and Distribution Spec -- the official mechanism to list related artifacts by subject (digest) -- is part of OCI Distribution 1.1, and spec text now clarifies fallback behavior when referrers are not supported (registries SHOULD return 200 on supported referrers calls; 404 or fallback tag otherwise).

GHCR -- Lack of referrers

GHCR implements OCI image formats but does not support the OCI referrers API endpoint for generic discovery of artifacts by subject. Community threads confirm queries against /v2/<name>/referrers/<digest> do not work. The practical implication: you must use GitHub's specific Attestations/Policy APIs or fetch artifacts by known SHA.

ECR -- OCI 1.1 support

AWS has documented support for OCI Image and Distribution 1.1 specs, including image referrers, SBOMs, signatures, and non-image artifact distribution. OCI-aware clients (ORAS, containerd tooling) should be able to list and pull referrers by digest. Referrers count toward storage and lifecycle policies; include these artifact patterns explicitly in lifecycle/GC rules.

Google Artifact Registry -- attachments + listing

Google Artifact Registry provides an attachments model for metadata (SBOMs, provenance) tied to an artifact. Attachments can be listed with gcloud artifacts attachments list and via console UI. IAM roles govern access, and some features are in public preview.

Red Hat Quay / Quay.io -- OCI referrers implemented

Quay has announced support for the OCI Referrers API, enabling clients to query relationships by subject and artifactType. Watch for deployment flags or admin toggles that control this feature.

Harbor -- evolving but partial

Harbor can store OCI artifacts, but its implementation of referrers has historically lagged UI classification: cosign or SBOM referrers may be accepted at the API level while displayed as "UNKNOWN" in UI. Active work is on improving OCI 1.1 support, but UI behavior and mediaType classification may still lag the API capabilities in releases around v2.15+.

Spec and ecosystem nuance

OCI Distribution 1.1 spec updates explicitly require registries that support referrers to return successful responses for referrers endpoints; otherwise clients should fall back to tag-by-digest conventions. Because referrers support is optional and not universal yet, generic clients must detect support at runtime and fallback where needed. Many registries (e.g., Docker Hub, GitLab) can store OCI artifacts with subject fields, but will not expose them via a referrers endpoint.

References