Repositories, artifacts, and tags
Registry stores OCI artifacts — container images, Helm charts, and anything else that follows the OCI image specification — inside your workspace. The model has three levels, and the first of them is the workspace you already have.
Repositories
Section titled “Repositories”A repository is a named collection of artifacts, and it is the top-level registry resource. It lives directly inside a workspace: there is no additional grouping layer between the two.
A repository has:
- a name, unique within its workspace, which may itself contain slashes so
that
team/service/backendis one repository rather than a hierarchy; - a format — Docker, Helm, or OCI — fixed when the repository is created and never changed afterwards;
- a visibility, public or private;
- an optional immutable-tags setting, which prevents a tag from being moved once it points at an artifact.
Because a repository belongs to a workspace, everything that governs the workspace governs the repository: the access model, the audit trail, and the lifecycle. By default a repository is readable only from inside its own workspace; a cross-workspace pull grant is what lets principals of another workspace pull from it, read-only, and it is the source workspace’s own act to create one.
Artifacts
Section titled “Artifacts”An artifact is one OCI artifact: a manifest together with the blobs it
references. It is identified by the content digest of its manifest, written
sha256: followed by the hex digest.
The digest is derived from the content, so it is exact and stable. Two artifacts with the same digest are the same bytes; an artifact’s digest cannot be reassigned to different content.
Blobs are shared within a workspace: if two repositories in the same workspace hold artifacts with a layer in common, that layer is stored once. Blobs are never shared across workspaces, even when the bytes are identical, so one workspace can never learn what another holds by observing storage.
A blob is reachable only through a repository that references it. Asking for a blob by digest through a repository that does not reference it is answered as though the blob does not exist.
A tag is a movable name that points at an artifact — v1.4.0, latest, a
commit SHA. Tags are how people refer to artifacts; digests are how machines do.
Deleting a tag removes the name, not the artifact. The artifact remains, and is still reachable by digest, unless the tag was its last reference.
When a repository has immutable tags enabled, a tag that already points at an artifact cannot be moved to a different one.
Choosing between a tag and a digest
Section titled “Choosing between a tag and a digest”A tag can be repointed, so pulling by tag means “whatever this name points at now”. A digest cannot, so pulling by digest means “exactly these bytes”.
For a deployment you intend to reproduce, pull by digest. If a tag is repointed while a pull is in progress, that pull still completes consistently — the client resolved a digest before fetching content, and continues to fetch that artifact.