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

## What It Checks
Sends an authenticated HTTP POST to `<registryUrl>/v2/<testRepo>/blobs/uploads/` to initiate a blob upload session. Uses the test repository from `OCI:TestRepository` or `OCI:PushTestRepository` (default `stellaops/doctor-test`). Only runs if credentials are configured. The check **passes** on 202 Accepted (the upload session is immediately cancelled by sending a DELETE to the returned Location header), **fails** on 401 (invalid credentials), **fails** on 403 (valid credentials but no push permission), and **fails** on connection errors or timeouts. No data is actually written to the registry.

## Why It Matters
Push authorization is required for storing attestations, SBOMs, signatures, and promoted images in the registry. Without push access, Stella Ops cannot attach evidence artifacts to releases, sign images, or complete promotion workflows. This check verifies the actual push permission grant, not just credential validity, using a non-destructive probe that leaves no artifacts behind.

## Common Causes
- Credentials are valid but lack push (write) permissions
- Repository does not exist and the registry does not support auto-creation
- Service account has read-only access
- Organization or team policy restricts push to specific accounts
- Token has been revoked or expired
- IP or network restrictions prevent write operations

## How to Fix

### Docker Compose
```bash
# Test push manually
echo "test" | docker push registry.example.com/stellaops/doctor-test:probe

# Grant push permissions to the service account in your registry UI

# Set a writable test repository
echo 'OCI__PushTestRepository=myorg/stellaops-test' >> .env
docker compose restart platform
```

### Bare Metal / systemd
```bash
# Test push authorization with curl
curl -X POST \
  -u stellaops-svc:<password> \
  https://registry.example.com/v2/stellaops/doctor-test/blobs/uploads/

# Expected: 202 Accepted with Location header

# Fix permissions in registry
# Harbor: Add stellaops-svc as Developer/Admin to the project
# GitLab: Grant Reporter+ role to the service account
# ECR: Attach ecr:InitiateLayerUpload policy

sudo systemctl restart stellaops-platform
```

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

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

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