---
checkId: check.integration.oci.capabilities
plugin: stellaops.doctor.integration
severity: info
tags: [registry, oci, capabilities, compatibility]
---
# OCI Registry Capability Matrix

## What It Checks
Probes the configured OCI registry for five capabilities using a test repository (`OCI:TestRepository`, default `library/alpine`):

1. **Distribution version** -- GET `/v2/`, reads `OCI-Distribution-API-Version` or `Docker-Distribution-API-Version` header.
2. **Referrers API** -- GET `/v2/<repo>/referrers/<digest>` with OCI accept header; passes if 200 or if a 404 response contains OCI index JSON.
3. **Chunked upload** -- POST `/v2/<repo>/blobs/uploads/`; passes on 202 Accepted (upload session is immediately cancelled).
4. **Cross-repo mount** -- POST `/v2/<repo>/blobs/uploads/?mount=<digest>&from=library/alpine`; passes on 201 Created or 202 Accepted.
5. **Delete support** (manifests and blobs) -- OPTIONS request to check if `DELETE` appears in the `Allow` header.

Calculates a capability score (N/5). **Warns** if referrers API is unsupported, **info** if any other capability is missing, **passes** if all 5 are supported. **Fails** on connection errors.

## Why It Matters
Different OCI registries support different subsets of the OCI Distribution Spec. Stella Ops uses referrers for attestation linking, chunked uploads for large SBOMs, cross-repo mounts for efficient promotion, and deletes for garbage collection. Knowing the capability matrix upfront prevents mysterious failures during release operations and allows operators to configure appropriate fallbacks.

## Common Causes
- Registry does not implement OCI Distribution Spec v1.1 (no referrers API)
- Registry has delete operations disabled by policy
- Chunked upload is disabled in registry configuration
- Cross-repo mount is not supported by the registry implementation
- Registry version is too old for newer OCI features

## How to Fix

### Docker Compose
```bash
# Check registry type and version
docker compose exec gateway curl -sv https://registry.example.com/v2/ \
  -o /dev/null 2>&1 | grep -i 'distribution-api-version'

# If referrers API is missing, consider upgrading the registry
# Harbor 2.6+, Quay 3.12+, ACR, ECR, GCR/Artifact Registry support referrers

# Enable delete in Harbor
# Update harbor.yml: delete_enabled: true
# Restart Harbor
```

### Bare Metal / systemd
```bash
# Test referrers API directly
curl -H "Accept: application/vnd.oci.image.index.v1+json" \
  https://registry.example.com/v2/library/alpine/referrers/sha256:abc...

# Test chunked upload
curl -X POST https://registry.example.com/v2/test/blobs/uploads/

# Enable delete in Docker Distribution
# In /etc/docker/registry/config.yml:
#   storage:
#     delete:
#       enabled: true
sudo systemctl restart docker-registry
```

### Kubernetes / Helm
```yaml
# values.yaml (for Harbor)
harbor:
  registry:
    deleteEnabled: true

# values.yaml (for Stella Ops)
oci:
  registryUrl: https://registry.example.com
  testRepository: library/alpine
```
```bash
helm upgrade stellaops ./chart -f values.yaml
```

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

## Related Checks
- `check.integration.oci.registry` -- basic registry connectivity
- `check.integration.oci.referrers` -- focused referrers API check with digest resolution
- `check.integration.oci.credentials` -- credential validation
- `check.integration.oci.pull` -- pull authorization
- `check.integration.oci.push` -- push authorization