---
checkId: check.integration.oci.pull
plugin: stellaops.doctor.integration
severity: fail
tags: [registry, oci, pull, authorization, credentials]
---
# OCI Registry Pull Authorization

## 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
- Credentials are invalid or expired
- Token has been revoked
- Anonymous pull is not allowed and no credentials are configured
- Service account has been removed from the repository's access list
- Repository access restricted by IP, network, or organization policy
- Test image does not exist in the registry (404 -- configure `OCI:TestRepository`)

## How to Fix

### Docker Compose
```bash
# 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
```bash
# 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
```yaml
# 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.pull
```

## Related Checks
- `check.integration.oci.credentials` -- validates credential configuration and token validity
- `check.integration.oci.push` -- verifies push authorization
- `check.integration.oci.registry` -- basic registry connectivity