Container registry

Registries speak the OCI Distribution Specification, which grew out of the Docker Registry HTTP API V2. Everything lives under /v2/: a client pulls by requesting GET /v2/<name>/manifests/<reference>, where the reference is a tag or a digest, and then fetches each layer and config via GET /v2/<name>/blobs/<digest>. Pushing is the reverse: blobs are uploaded first (POST to open an upload session, optional PATCH chunks, a final PUT with ?digest=), and the manifest is pushed last, which is what makes the new tag visible. Blobs are deduplicated by digest across repositories, so a common base layer is stored once. Authentication is usually the token flow: the registry answers 401 with a WWW-Authenticate: Bearer challenge naming a token service and a scope such as repository:team/app:pull,push, and the client returns with a short-lived JWT.

Distribution spec 1.1 added the referrers API (GET /v2/<name>/referrers/<digest>), which lists artifacts whose subject field points at a given manifest. This is how signatures, SBOMs, SLSA provenance and scan results are attached to an image without changing its digest; older registries without the API are served by a fallback tag scheme (sha256-<digest>).

Implementations range from the CNCF Distribution project and Harbor (with built-in scanning, replication, quotas and robot accounts) to Zot and Quay, plus the cloud services Amazon ECR, Azure Container Registry, Google Artifact Registry and GitHub Container Registry. Docker Hub is the implicit default: an unqualified name such as nginx expands to docker.io/library/nginx, a behaviour that creates ambiguity and has led tools such as Podman to require fully qualified names or explicit aliases.

The registry sits at a trust junction in the software supply chain. Risks include mutable tags being overwritten (mitigated by tag-immutability settings and deploying by digest), leaked push credentials from CI, publicly readable private repositories exposing embedded secrets, typosquatted or malicious public images (cryptominers in look-alike repositories on Docker Hub are a recurring finding), and dependence on a public registry's availability and pull rate limits. Common controls are a private pull-through cache or mirror so that production pulls only from an internal registry, separate push identities per pipeline using short-lived OIDC federation rather than static passwords, continuous scanning of stored images, retention and garbage-collection policies, and an admission controller that refuses images from unapproved registries or without a valid signature. A registry is distinct from a package repository such as npm or PyPI in serving whole runtime filesystems, and distinct from the runtime, which only consumes what the registry serves.