Docker / OCI

OrbitalReg's container registry implements the OCI Distribution Spec v1.1 plus Docker Registry HTTP API v2 compatibility. Tools that work with Harbor / ghcr.io / Docker Hub work without adaptation.

Repository types

• Local — docker push into a project's repo.
• Remote — pull-through cache for docker.io, ghcr.io, quay.io, etc. The first request to each digest fetches and caches.
• Virtual — federated view across local + remote repos.

Endpoint shape

https://orbitalreg.example.com/<project>/<repo>/<image>:<tag>

For example, the canonical "library/alpine" lives at:

docker pull orbitalreg.example.com/acme/dockerhub-mirror/library/alpine:latest

docker login

echo $ORBITALREG_TOKEN | docker login orbitalreg.example.com \
  -u $ORBITALREG_USER --password-stdin

For air-gapped or short-lived auth, use the OIDC token exchange flow.

Pushing

docker tag my-app:1.0.0 orbitalreg.example.com/acme/internal/my-app:1.0.0
docker push orbitalreg.example.com/acme/internal/my-app:1.0.0

Multi-arch manifest lists are preserved — push from buildx or skopeo without flattening.

OCI artifacts

Generic OCI artifacts (Helm charts via helm push, ORAS-pushed SBOM attestations, cosign signatures) are accepted via the same distribution endpoint. The Content-Type of the manifest determines the artifact type for the Detection pipeline.

Referrers API (OCI 1.1)

The registry implements the OCI Distribution 1.1 Referrers API:

GET /v2/<project>/<repo>/<image>/referrers/<digest>
GET /v2/<project>/<repo>/<image>/referrers/<digest>?artifactType=<media-type>

A manifest pushed with a subject descriptor (cosign signatures, SBOMs, in-toto attestations) is indexed at push time, and the push response carries the OCI-Subject header — the signal clients use to prefer the Referrers API over the legacy fallback tag schema (sha256-<digest>.sig tags), which keeps working unchanged for older tooling. The response is an OCI image index of descriptors; an unknown or unreferenced digest returns an empty index (200, per spec), and the artifactType filter is exact-match with OCI-Filters-Applied: artifactType set on the response. Subjects inside manifests cached from an upstream (remote-proxy repositories) are indexed the same way, so referrers resolve against the cache too.

Deleting a referrer manifest (by digest) removes it from the referrers list automatically — the index is derived from the manifest rows, not maintained separately.

Detection

Container images are scanned by Trivy and Grype on each push, with Syft producing the SBOM. Findings carry the layer + package name so the operator can trace back to a base image.

The default policy quarantines on CRITICAL findings; override per project under Project settings → Security → Quarantine threshold.

Sigstore / cosign

cosign sign \
  --identity-token=$CI_JOB_JWT_V2 \
  orbitalreg.example.com/acme/internal/my-app@sha256:…

The verifier consults sigstore_trust_policies to decide whether the signing identity is acceptable for the target repo.

Garbage collection

Layer GC is per-CAS and runs hourly. A layer becomes eligible for GC when no active manifest references it. The GC window is operator-tunable; default is "delete after 24 h of no references" to give CI runs a buffer.

Migration from Harbor

Harbor's HTTP API is a superset of the OCI Distribution Spec, so migrating is a docker pull / docker tag / docker push loop. Larger estates can use skopeo sync to move thousands of images in parallel:

skopeo sync --src docker --dest docker \
  harbor.example.com/library \
  orbitalreg.example.com/acme/library

Pull-through cache cleanup

The pull-through cache for a remote repo is bounded by the repo's retention policy. A common shape:

name: cache-keep-30d
rules:
  - keep_by_age:
      max_age_days: 30
      match_pulled_in_last_days: 14

That keeps any image pulled in the last 14 days for 30 days from its last access — covering the typical "this base image is fetched once per CI run" pattern.