Artifact Registry

The Distr Artifact Registry is a built-in, OCI-compliant registry designed for AI and software companies to distribute Docker images and Helm Charts, SBOMs and other OCI artifacts to self-managed and BYOC environments. It also includes tag-based access and licensing controls. The registry also provides detailed download analytics that let you monitor which versions of your software are being used by each customer.

Use it to publish versioned artifacts, enforce entitlement rules, and track consumption across your customer base.

• Multi-artifact support: Distribute Docker Images, Helm Charts, Terraform Modules, Zarf packages, and any OCI-compliant artifact
• Software supply chain security: Store SBOMs and signatures for image verification
• Visibility: Get insights into which customers are using which artifacts and versions
• Open standards: Built on the OCI specification and compatible with existing tooling (Docker, ORAS, Helm, etc.)
• Built-in licensing (beta): Bind artifact versions to entitlements for fine-grained customer access control

Want a quick overview of how it works? Watch this short walkthrough:

The Artifact List page lets you view all artifacts stored in your registry. It provides an overview of pull counts across all tags, along with insights into which users and customers are using each artifact.

The artifact details page gives you a complete view of all tags associated with a specific artifact. You can see the OCI URL, upload date, and artifact size, along with pull counts for each tag.

Every artifact has a versioning strategy, which determines how its versions are sorted on the artifact details page and which tag counts as the newest:

• Chronological versioning orders versions by the time they were pushed, whatever their tags are named. It is the default and accepts any tag.
• Semantic versioning orders versions by SemVer precedence, so 1.10.0 is newer than 1.9.0 and 2.0.0 is newer than 2.0.0-rc.1. A version with several tags is ranked by its highest one.

Under semantic versioning, every tag has to be a SemVer version with exactly three numbers, optionally prefixed with v: 1.2.3, v1.2.3 and 1.2.3-rc.1 are accepted, 1.2, latest and main are not. The registry rejects a push of any other tag with 403 Forbidden and the error code DENIED. Signature and attestation tags (sha256-<digest>.sig, .att, .sbom and .cosign) are exempt, so signing an image with cosign keeps working.

Change the strategy on the artifact details page. Switching an artifact that holds tags that are not SemVer versions to semantic versioning deletes those tags, after Distr has named them and you have confirmed. Their pull history is deleted with them, and pushed tags cannot be restored. The switch is refused if one of them cannot be deleted, for example because an entitlement grants exactly that version, and if none of the artifact’s tags is a SemVer version.

A single artifact can be made public, so anyone who knows its name can pull it without credentials. This is meant for what you want to hand out freely, an installer image, a CLI, an agent chart or a public demo, while everything else in the registry stays private.

Open the artifact details page and pick Make public from the menu in the top right. The artifact then carries a Public badge everywhere it is listed, and Make private in the same menu requires credentials again. Only organization admins can change it.

Docker, Podman, Skopeo, ORAS, Helm and anything speaking the HTTP API directly pull a public artifact with no setup at all:

docker pull registry.example.com/acme/my-image:1.0.0
oras pull registry.example.com/acme/my-artifact:1.0.0
helm pull oci://registry.example.com/acme/my-chart --version 1.0.0
curl -sSL https://registry.example.com/v2/acme/my-image/manifests/1.0.0 \
  -H 'Accept: application/vnd.oci.image.manifest.v1+json'

Private artifacts still need credentials: log in with docker login, podman login or helm registry login, using a PAT as the password.

Anonymous pulls are rate limited per client IP address, considerably more strictly than the pull limits of the large public registries. A client that exceeds them gets 401 Unauthorized with a request to authenticate and a Retry-After header. Authenticated pulls are never rate limited, so a client that holds a PAT authenticates with it and pulls on, and a customer who runs into the limit only has to log in. The answer is a 401 rather than 429 Too Many Requests because OCI clients send their credentials only once they have seen a 401, so a 429 would lock out a customer whose credentials are sitting unused in the client’s config file. Self-hosted instances can change the limits, see the REGISTRY_ANONYMOUS_* variables.

Every anonymous pull is recorded in the download analytics like any other pull, marked as Anonymous since there is no user or customer behind it.

The main Distr dashboard also provides a global view of which artifacts each end customer has consumed, including version details and a health status.

The Distr registry protects artifacts and tags that are referenced in entitlements, so customers keep access to their licensed software.

You can delete individual tags from an artifact through the API, the UI and the registry itself (DELETE /v2/<name>/manifests/<tag>). However, the system enforces several validation rules to prevent breaking customer access.

Only named tags such as v1.0.0 can be deleted. A digest reference (sha256:…) is rejected with 400 Bad Request, which also affects clients that resolve a tag to its digest before deleting it.

Tag deletion succeeds when all of these conditions are met:

• The tag exists
• No artifact entitlement grants all versions of the artifact
• If an entitlement grants exactly the version the tag points at, another tag must point at that version as well
• If it is the last tag of the artifact, no entitlement references the artifact at all

Deleting the last tag of an artifact deletes the entire artifact, as described in Deleting Artifacts. When this happens through the registry API, the response carries a Warning header saying so. A pull-through cache artifact is the exception: its last tag cannot be deleted, and the next sync restores a deleted tag unless it has been removed from the upstream repository.

Deleting a tag also deletes the version the tag pointed at, so that its blobs can be reclaimed. For a multi-arch image, this extends to the per-architecture manifests the index referenced. A version is only deleted when nothing references it any more, that is when no other tag points at it and no other version references it (a per-architecture manifest shared with another index is kept).

An entitlement that grants a version deleted this way loses that version, and keeps every other artifact and version it grants.

Once a version is deleted, it can no longer be pulled by its digest. The blobs themselves are removed by the blob cleanup job, which a self-hosted instance has to schedule.

Scenario 1: Safe deletion

Artifact: myapp Tags: v1.0.0, v1.0.1, latest (all point to different digests) License: References sha256:abc123 (v1.0.0’s digest)

Action: Delete tag “v1.0.1” Result: Success - v1.0.1 is not licensed

Scenario 2: Blocked deletion - licensed digest

Artifact: myapp Tags: v1.0.0 (points to sha256:abc123) License: References sha256:abc123

Action: Delete tag “v1.0.0” Result: Blocked (400) - Cannot delete last non-SHA tag for licensed digest

Scenario 3: Last tag deletes the artifact

Artifact: myapp Tags: v1.0.0 (only tag remaining) No licenses

Action: Delete tag “v1.0.0” Result: Success - the artifact myapp is deleted as well

You can delete entire artifacts from your registry, which will cascade to all associated versions, tags and historical download data.

Artifacts can be deleted when they are not referenced in any entitlement, including an expired one.

• Check entitlements first: Before deleting artifacts or tags, verify they are not referenced in customer entitlements
• Use caution with tags: Deleting tags can affect customer access if not done carefully
• Monitor usage: Review the Downloads section to understand which artifacts and versions are actively used
• Mind the last tag: Deleting the last tag of an artifact deletes the artifact with it