Repositories, tags and images
How repositories, tags, digests, untagged images, multi-platform images and referrers relate in your registry.
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.