checkId: check.integration.oci.pull plugin: stellaops.doctor.integration severity: fail tags: [registry, oci, pull, authorization, credentials]

OCI Registry Pull Authorization

This Doctor check verifies that the configured credentials are actually granted permission to pull from the OCI registry, not merely that they authenticate. It is aimed at operators and DevOps engineers diagnosing scan, SBOM-extraction, and deployment failures that survive a passing credentials check.

What It Checks

Sends an authenticated HTTP HEAD request to <registryUrl>/v2/<testRepo>/manifests/<testTag> with OCI and Docker manifest accept headers. Uses the test repository from OCI:TestRepository (default library/alpine) and test tag from OCI:TestTag (default latest). The check passes on 2xx (records manifest digest and content type), returns info on 404 (test image not found – cannot verify), fails on 401 (invalid credentials), fails on 403 (valid credentials but no pull permission), and fails on connection errors or timeouts.

Why It Matters

Pull authorization is the most fundamental registry operation. Stella Ops pulls images for scanning, SBOM extraction, attestation verification, and deployment. If pull authorization fails, the entire image-based workflow is blocked. This check tests actual pull permissions rather than just credential validity, catching permission misconfigurations that check.integration.oci.credentials cannot detect.

Common Causes

How to Fix

Docker Compose

# Test pull manually
docker pull registry.example.com/library/alpine:latest

# Check configured test repository
grep 'OCI__TESTREPOSITORY\|REGISTRY__TESTREPOSITORY' .env

# Set a valid test image that exists in your registry
echo 'OCI__TestRepository=myorg/base-image' >> .env
echo 'OCI__TestTag=latest' >> .env
docker compose restart platform

Bare Metal / systemd

# Test pull authorization with curl
curl -I -H "Accept: application/vnd.oci.image.manifest.v1+json" \
  -u stellaops-svc:<password> \
  https://registry.example.com/v2/library/alpine/manifests/latest

# Configure a test image that exists in your registry
sudo nano /etc/stellaops/appsettings.Production.json
# Set OCI:TestRepository and OCI:TestTag
sudo systemctl restart stellaops-platform

Kubernetes / Helm

# values.yaml
oci:
  registryUrl: https://registry.example.com
  testRepository: myorg/base-image
  testTag: latest

helm upgrade stellaops ./chart -f values.yaml

Verification

stella doctor --check check.integration.oci.pull