---
checkId: check.integration.oci.referrers
plugin: stellaops.doctor.integration
severity: warn
tags: [registry, oci, referrers, compatibility, oci-1.1]
---
# OCI Registry Referrers API Support

## What It Checks
First resolves the manifest digest for the test image (`OCI:TestRepository`:`OCI:TestTag`, defaults to `library/alpine:latest`) by sending a HEAD request to the manifests endpoint and reading the `Docker-Content-Digest` header. Then probes the referrers API at `<registryUrl>/v2/<repo>/referrers/<digest>` with the `application/vnd.oci.image.index.v1+json` accept header. The check **passes** on 200 OK or on 404 if the response body contains OCI index JSON (valid response meaning no referrers exist yet). It **warns** on 404 without OCI index (API not supported, tag-based fallback required) or 405 Method Not Allowed. Returns **info** if the test image is not found (cannot verify). **Fails** on connection errors.

## Why It Matters
The OCI 1.1 referrers API enables artifact linking: attaching SBOMs, signatures, attestations, and VEX documents directly to container image manifests. Without it, Stella Ops must fall back to the tag-based referrer pattern (`sha256-{digest}.{artifactType}`), which is less efficient, harder to discover, and may conflict with registry tag naming policies. Knowing referrers API availability determines which linking strategy is used.

## Common Causes
- Registry does not implement OCI Distribution Spec v1.1
- Registry version is too old (pre-referrers API)
- Referrers API disabled in registry configuration
- Test image does not exist in registry (cannot resolve digest to probe)
- Credentials lack pull permissions for the test image

## How to Fix

### Docker Compose
```bash
# Check registry version and referrers support
docker compose exec gateway curl -sv \
  -H "Accept: application/vnd.oci.image.index.v1+json" \
  https://registry.example.com/v2/library/alpine/referrers/sha256:abc...

# Upgrade registry to a version supporting OCI 1.1 referrers:
# - Harbor 2.6+
# - Quay 3.12+
# - ACR (default)
# - ECR (default)
# - GCR/Artifact Registry (default)
# - Distribution 2.8+
```

### Bare Metal / systemd
```bash
# Verify registry version
curl -I https://registry.example.com/v2/ 2>&1 | grep -i distribution

# Test referrers API
DIGEST=$(curl -sI -H "Accept: application/vnd.oci.image.manifest.v1+json" \
  https://registry.example.com/v2/library/alpine/manifests/latest \
  | grep Docker-Content-Digest | awk '{print $2}' | tr -d '\r')

curl -H "Accept: application/vnd.oci.image.index.v1+json" \
  https://registry.example.com/v2/library/alpine/referrers/$DIGEST

# Upgrade the registry package
sudo apt upgrade docker-registry   # or equivalent
sudo systemctl restart docker-registry
```

### Kubernetes / Helm
```yaml
# Upgrade Harbor chart
helm upgrade harbor harbor/harbor --set registry.referrers.enabled=true

# Or configure Stella Ops with a test image that exists
# values.yaml
oci:
  registryUrl: https://registry.example.com
  testRepository: myorg/base-image
  testTag: latest
```
```bash
helm upgrade stellaops ./chart -f values.yaml
```

## Verification
```
stella doctor run --check check.integration.oci.referrers
```

## Related Checks
- `check.integration.oci.capabilities` -- broader capability matrix including referrers
- `check.integration.oci.registry` -- basic registry connectivity
- `check.integration.oci.pull` -- pull authorization (needed to resolve test image digest)