---
checkId: check.integration.oci.credentials
plugin: stellaops.doctor.integration
severity: fail
tags: [registry, oci, credentials, secrets, auth]
---
# OCI Registry Credentials

## What It Checks
Determines the authentication method from configuration: bearer token (`OCI:Token` / `Registry:Token`), basic auth (`OCI:Username` + `OCI:Password` / `Registry:Username` + `Registry:Password`), or anonymous. Immediately **fails** if a username is provided without a password. Then validates credentials by sending an authenticated HTTP GET to `<registryUrl>/v2/`. The check **passes** on 200 OK, or on 401 if the response includes a `WWW-Authenticate: Bearer` challenge and basic credentials are configured (OAuth2 token exchange scenario). It **fails** on 401 (invalid credentials) or 403 (forbidden), and **fails** on connection errors or timeouts.

## Why It Matters
Invalid or expired registry credentials cause image pull/push failures across all deployment pipelines. Because credentials are often rotated on a schedule, this check provides early detection of expired tokens before they silently break promotions, SBOM ingestion, or attestation storage. A username-without-password misconfiguration indicates a secret reference that failed to resolve.

## Common Causes
- Credentials are invalid or have been rotated without updating the configuration
- Token has been revoked by the registry administrator
- Username provided without a corresponding password (broken secret reference)
- Service account token expired
- IP address or network not in the registry's allowlist

## How to Fix

### Docker Compose
```bash
# Check credential configuration
grep 'OCI__USERNAME\|OCI__PASSWORD\|OCI__TOKEN\|REGISTRY__' .env

# Test credentials manually
docker login registry.example.com

# Rotate credentials
echo 'OCI__Username=stellaops-svc' >> .env
echo 'OCI__Password=<new-password>' >> .env
docker compose restart platform
```

### Bare Metal / systemd
```bash
# Check credential configuration
cat /etc/stellaops/appsettings.Production.json | jq '.OCI | {Username, Password: (if .Password then "****" else null end), Token: (if .Token then "****" else null end)}'

# Test with curl
curl -u stellaops-svc:<password> https://registry.example.com/v2/

# Update credentials
sudo nano /etc/stellaops/appsettings.Production.json
sudo systemctl restart stellaops-platform
```

### Kubernetes / Helm
```yaml
# values.yaml
oci:
  registryUrl: https://registry.example.com
  existingSecret: stellaops-registry-creds   # Secret with username/password keys
```
```bash
# Create or update the secret
kubectl create secret generic stellaops-registry-creds \
  --from-literal=username=stellaops-svc \
  --from-literal=password=<new-password> \
  --dry-run=client -o yaml | kubectl apply -f -

helm upgrade stellaops ./chart -f values.yaml
```

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

## Related Checks
- `check.integration.oci.registry` -- basic connectivity (does not test auth)
- `check.integration.oci.pull` -- verifies pull authorization with these credentials
- `check.integration.oci.push` -- verifies push authorization with these credentials