Registry Compatibility Matrix

Sprint: SPRINT_0127_001_0001_oci_referrer_bundle_export Module: ExportCenter

This document provides detailed compatibility information for OCI referrer discovery across container registries.

OCI 1.1 Referrers API Support

The OCI Distribution Spec v1.1 introduced the native referrers API (), which enables efficient discovery of artifacts linked to container images. Not all registries support this API yet.

Support Matrix

Legend

• OCI 1.1 API: Native support for endpoint
• Fallback Tags: Support for tag-schema discovery pattern ()
• Artifact Type Filter: Support for query parameter

Per-Registry Details

Docker Hub

• API Support: Partial OCI 1.1 support
• Fallback: Yes, via tag-based discovery
• Authentication: Bearer token via Docker Hub auth service
• Rate Limits: 100 pulls/6 hours (anonymous), 200 pulls/6 hours (authenticated)
• Known Issues:
  • Rate limiting can affect large bundle exports
  • Some artifact types may not be discoverable via native API

GitHub Container Registry (GHCR)

• API Support: No native referrers API
• Fallback: Yes, required for all referrer discovery
• Authentication: GitHub PAT or GITHUB_TOKEN with scope
• Rate Limits: GitHub API rate limits apply
• Known Issues:
  • Referrers must be pushed using tag-schema pattern
  • Artifact types embedded in tag suffix (e.g., , , )

Google Container Registry / Artifact Registry

• API Support: Full OCI 1.1 support
• Fallback: Yes, as backup
• Authentication: Google Cloud service account or gcloud auth
• Rate Limits: Generous; project quotas apply
• Known Issues:
  • Google Artifact Registry also exposes an attachments model (gcloud artifacts attachments list) as an alternative metadata UX alongside the standard OCI referrers endpoint. StellaOps uses the standard OCI API; the Google-specific attachments API is not required.
  • Some non-Docker format features may be in public preview; Docker/OCI artifact discovery is stable.

Amazon Elastic Container Registry (ECR)

• API Support: Full OCI 1.1 support
• Fallback: Yes, as backup
• Authentication: IAM role or access keys via
• Rate Limits: 1000 requests/second per region
• Known Issues:
  • Requires IAM permissions for OCI operations
  • Cross-account referrer discovery needs proper IAM policies

Azure Container Registry (ACR)

• API Support: Full OCI 1.1 support
• Fallback: Yes, as backup
• Authentication: Azure AD service principal or managed identity
• Rate Limits: Tier-dependent (Basic: 1000 reads/min, Standard: 3000, Premium: 10000)
• Known Issues: None significant

Harbor

• API Support: Full OCI 1.1 support in Harbor 2.0+
• Fallback: Yes
• Authentication: Harbor user credentials or robot account
• Rate Limits: Configurable at server level
• Known Issues:
  • Harbor 1.x does not support referrers API
  • Project-level permissions required
  • Harbor UI may display cosign signatures or SBOM referrers as “UNKNOWN” artifact type in versions around v2.15+; this is a Harbor UI classification issue and does not affect API-level discovery or StellaOps functionality

Quay.io / Red Hat Quay

• API Support: Partial (version-dependent); Red Hat has announced full OCI Referrers API support on Quay.io
• Fallback: Yes
• Authentication: Robot account or OAuth token
• Rate Limits: Account tier dependent
• Known Issues:
  • Support varies significantly by version
  • Some deployments may have referrers API disabled
  • Self-hosted Quay deployments may require admin toggles or deployment flags to enable the referrers API; if referrer discovery is inconsistent, verify the feature is enabled in the Quay configuration

JFrog Artifactory

• API Support: Partial (requires OCI layout)
• Fallback: Yes
• Authentication: API key or access token
• Rate Limits: License-dependent
• Known Issues:
  • Repository must be configured as Docker with OCI layout
  • Referrers API requires Artifactory 7.x+

GitLab Container Registry

• API Support: No native referrers API
• Fallback: Yes, required for all referrer discovery
• Authentication: GitLab deploy token, personal access token, or CI job token with read_registry scope
• Rate Limits: Instance-dependent
• Known Issues:
  • Stores OCI artifacts with subject field but does not expose a referrers endpoint
  • Referrer discovery must use tag-schema fallback or GitLab-specific APIs
  • Discovery behavior mirrors GHCR: push referrers with tag-schema pattern and enumerate via tag listing

Discovery Methods

Native Referrers API (OCI 1.1)

The preferred method queries the registry referrers endpoint directly:

Fallback Tag-Schema Discovery

For registries without OCI 1.1 support, tags following the pattern are enumerated:

Each matching tag is then resolved to get artifact metadata.

Troubleshooting

Common Issues

Diagnostic Commands

Related Documentation

• Export Center Architecture
• Offline Bundle Format
• Registry Referrer Troubleshooting Runbook
• OCI Distribution Spec v1.1

Imposed rule: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.