# 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](push-an-image.md)), or a pull under a pull-through cache rule
brings its first image in (see [Use a pull-through cache](use-a-pull-through-cache.md)). 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](make-tags-immutable.md)).

## 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](delete-a-tag-or-image.md)) 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`.

## Related

- [Push an image](push-an-image.md)
- [Pull an image](pull-an-image.md)
- [Storage and cleanup](storage-and-cleanup.md)
