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

OCI Registry Push Authorization

This Doctor check verifies that the configured credentials are granted permission to push to the OCI registry, using a non-destructive probe that writes no data. It is aimed at operators and DevOps engineers diagnosing failures to store attestations, SBOMs, signatures, and promoted images.

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

How to Fix

Docker Compose

# Test push manually (tag a small local image, then push)
docker pull alpine:latest
docker tag alpine:latest registry.example.com/stellaops/doctor-test:probe
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

# 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

# values.yaml
oci:
  registryUrl: https://registry.example.com
  pushTestRepository: myorg/stellaops-test
  existingSecret: stellaops-registry-creds

helm upgrade stellaops ./chart -f values.yaml

Verification

stella doctor --check check.integration.oci.push