---
checkId: check.integration.oci.registry
plugin: stellaops.doctor.integration
severity: warn
tags: [connectivity, oci, registry]
---
# OCI Registry Connectivity

## What It Checks
Reads the registry URL from `OCI:RegistryUrl` or `Registry:Url`. Sends an HTTP GET to `<registryUrl>/v2/` (the OCI Distribution Spec base endpoint). The check **passes** if the response is 200 (open registry) or 401 (registry reachable, auth required), **warns** on any other status code, and **fails** on connection errors.

## Why It Matters
The OCI registry is the central artifact store for container images, SBOMs, attestations, and signatures. If the registry is unreachable, image pulls fail during deployment, SBOM scans cannot fetch manifests, attestation verification cannot retrieve signatures, and promotions are blocked. This is a foundational dependency for nearly every Stella Ops workflow.

## Common Causes
- Registry URL is incorrect (typo, wrong port, wrong scheme)
- Network connectivity issues between Stella Ops and the registry
- Registry service is down or restarting
- Registry does not support the OCI Distribution spec at `/v2/`
- Registry endpoint is misconfigured (path prefix required)

## How to Fix

### Docker Compose
```bash
# Check registry configuration
grep 'OCI__REGISTRYURL\|REGISTRY__URL' .env

# Test the /v2/ endpoint from inside the network
docker compose exec gateway curl -sv https://registry.example.com/v2/

# Update registry URL
echo 'OCI__RegistryUrl=https://registry.example.com' >> .env
docker compose restart platform
```

### Bare Metal / systemd
```bash
# Verify configuration
cat /etc/stellaops/appsettings.Production.json | jq '.OCI'

# Test connectivity
curl -v https://registry.example.com/v2/

# Fix configuration
sudo nano /etc/stellaops/appsettings.Production.json
sudo systemctl restart stellaops-platform
```

### Kubernetes / Helm
```yaml
# values.yaml
oci:
  registryUrl: https://registry.example.com
```
```bash
helm upgrade stellaops ./chart -f values.yaml
```

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

## Related Checks
- `check.integration.oci.credentials` -- validates registry credentials
- `check.integration.oci.pull` -- verifies pull authorization
- `check.integration.oci.push` -- verifies push authorization
- `check.integration.oci.referrers` -- checks OCI 1.1 referrers API support
- `check.integration.oci.capabilities` -- probes full capability matrix