git.stella-ops.org/docs/modules/export-center/registry-compatibility.md

# 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

| Registry | OCI 1.1 API | Fallback Tags | Artifact Type Filter | Notes |
|----------|-------------|---------------|---------------------|-------|
| **Docker Hub** | Partial | Yes | Limited | Rate limits may affect discovery; partial OCI 1.1 support |
| **GitHub Container Registry (GHCR)** | No | Yes | N/A | Uses tag-based discovery |
| **Google Container Registry (GCR)** | Yes | Yes | Yes | Full OCI 1.1 support |
| **Google Artifact Registry** | Yes | Yes | Yes | Full OCI 1.1 support |
| **Amazon ECR** | Yes | Yes | Yes | Requires proper IAM permissions for referrer operations |
| **Azure Container Registry (ACR)** | Yes | Yes | Yes | Full OCI 1.1 support |
| **Harbor 2.0+** | Yes | Yes | Yes | Full OCI 1.1 support; older versions require fallback |
| **Harbor 1.x** | No | Yes | N/A | Fallback only |
| **Quay.io** | Partial | Yes | Limited | Support varies by version and configuration |
| **JFrog Artifactory** | Partial | Yes | Limited | Requires OCI layout repository type |
| **Zot** | Yes | Yes | Yes | Full OCI 1.1 support |
| **Distribution (registry:2)** | No | Yes | N/A | Reference implementation without referrers API |

### 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**: None significant

### 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

### Quay.io / Red Hat Quay

- **API Support**: Partial (version-dependent)
- **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

### 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+

## 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

| Issue | Registry | Solution |
|-------|----------|----------|
| 404 on referrers endpoint | GHCR, Distribution | Use fallback tag discovery |
| Rate limit exceeded | Docker Hub | Authenticate or reduce concurrency |
| Permission denied | ECR, ACR | Check IAM/RBAC permissions |
| No referrers found | All | Verify artifacts were pushed with referrer relationship |
| Timeout | All | Increase timeout_seconds, check network |

### Diagnostic Commands



## Related Documentation

- [Export Center Architecture](architecture.md#oci-referrer-discovery)
- [Offline Bundle Format](../airgap/guides/offline-bundle-format.md#oci-referrer-artifacts)
- [Registry Referrer Troubleshooting Runbook](../../runbooks/registry-referrer-troubleshooting.md)
- [OCI Distribution Spec v1.1](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers)

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