Namespaces, repositories, and artifacts

Registry organises everything you store into a three-level hierarchy. This page explains each level, the artifact and tag model beneath it, and the invariants the service enforces. It stays conceptual; the API reference is where the exact fields, values, and limits live.

The resource hierarchy

flowchart LR
  classDef primary fill:#e8e8ff,stroke:#1100ff,stroke-width:2px,color:#0e0d1a
  classDef accent fill:#e2faec,stroke:#00e64d,stroke-width:2px,color:#0e0d1a
  classDef neutral fill:#ececf1,stroke:#302e45,stroke-width:2px,color:#0e0d1a

  ws["workspace"]:::neutral --> ns["Namespace"]:::primary
  ns --> repo["Repository"]:::accent
  repo --> art["Artifact"]:::primary
  art --> tag["Tag"]:::accent

Namespace

A namespace is the top-level isolation boundary inside a workspace’s registry. It owns repositories and namespace-scoped access policies. A namespace has a DNS-style name (3 to 63 characters, matching ^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$), is pinned to a region at creation, and exposes a registry host that clients log in against.

Deleting a namespace requires it to be empty. The call fails with a not-empty error while the namespace still has any repository, so delete the repositories first.

Repository

A repository is a named collection of artifacts inside a namespace, with the same DNS-style name rules. Two choices shape it:

Visibility: a repository is either private or public. A private repository requires a pull grant even to read from it; a public one is readable without one.
Format: Docker, Helm, or OCI. The format is chosen at creation and fixed afterward; an update does not change it.

A repository can also enforce an immutable-tag policy, where the registry refuses to overwrite an existing tag on push.

Deleting a repository removes the repository. The deployment-lock guard that protects an in-use artifact applies to artifact deletion, not to repository or namespace deletion (see The two deletes below).

Artifacts and tags

Artifact

An artifact is one OCI artifact: a manifest (the JSON document the registry stores) plus the blobs it references (image layers, configs). Key invariants:

It is identified by a content-derived digest of the form sha256:…, which is stable for the lifetime of the manifest. Identical content always yields the same digest.
It reports its total size (the manifest plus its referenced blobs) and its OCI media type, for example application/vnd.oci.image.manifest.v1+json.
It lists every tag currently pointing at the manifest, returned inline. The list is empty when the artifact is referenced only by digest.

You do not create an artifact through the control plane: artifacts come into existence when a client pushes through the registry data plane, and the control plane exposes them read-only.

Tag

A tag is a mutable label that points at an artifact’s manifest digest. A tag’s name is what you use in docker pull foo:<name> and is unique per repository; it records the digest it currently points at and when it was last pushed. A tag is immutable when the repository’s immutable-tag policy applies, in which case the registry refuses to overwrite it on push.

Multiple tags can point at the same digest. Re-pushing image:latest moves the latest tag to a new digest (unless that tag is immutable); the previously tagged manifest survives if any other tag still references it or it is referenced by digest.

The two deletes

Registry exposes two intentionally separate delete operations, because detaching a label is not the same as destroying content:

Deleting an artifact removes the manifest and detaches all of its tags. It is blocked when an active deployment lock pins the (repository, digest) pair.
Deleting a tag removes a single tag (a “detag”). The manifest survives if any other tag still references it, or if it is referenced by digest.

Both return an operation so the deletion is audited. An artifact may be addressed by either its digest (sha256:…) or a tag name; the registry resolves both.