Repositories, tags and images

How repositories, tags, digests, untagged images, multi-platform images and referrers relate in your registry.

Last updated 18 November 2026View as Markdown

Repositories

A repository name is 2–255 characters: lowercase path components joined by / (team/api), each made of letters and digits joined by ., _, __ or -. blobs, manifests, tags, referrers and uploads may not be a component. A name is unique in the organization.

A repository comes into being in one of three ways: you create it, a docker push names it for the first time (see Push an image), or a pull under a pull-through cache rule brings its first image in (see Use a pull-through cache). The last two are always private.

Tags and digests

An image is identified by its digest, sha256: and 64 hex characters. A tag is a name pointing at one image; a tag is 1–128 characters of letters, digits, _, . and -, and does not start with . or -. Pushing an image under a tag that already exists moves the tag to the new image, unless the repository's tags are immutable (see Make tags immutable).

Untagged images

When a push moves a tag, the image it pointed at keeps existing without a tag. It can still be pulled by digest, and its layers still cost storage until it is deleted, by you (see Delete a tag or an image) or by a lifecycle rule. The console lists it as a row of its own, marked untagged.

Multi-platform images and referrers

  • A multi-platform image (an image index) is one row in the console, with its platforms counted in it. Each platform image is stored as an image of its own and scanned on its own; the index itself is not scanned.
  • Signatures, SBOMs and attestations name the image they describe as their subject. They are listed by the OCI 1.1 referrers API, GET /v2/<repository>/referrers/<digest>, and the console marks them attached. Deleting an image deletes its referrers with it.
  • Helm charts and other OCI artifacts are stored like images; they are not scanned.

Limits

What Limit
Manifest 4 MiB; a larger one is refused with 413 and SIZE_INVALID
Digest algorithm sha256 only
Chunked uploads In order: a chunk that does not continue the upload is refused with 416

A layer is streamed to storage as it arrives and hashed on the way; a layer whose bytes do not match its digest is refused with DIGEST_INVALID.

Did this page help you?