Docker images in Artifact Registry

A Docker repository in Artifact Registry stores container images. The Docker package format implements the OCI Image and Distribution specification version 1.1.

Docker and OCI are separate formats. For information about the OCI format, see OCI artifacts in artifact registry.

Supported clients

The Docker package format supports the following clients:

• Docker CLI
• Podman

Authenticate

Prerequisites:

• The GitLab CLI, version 1.115.0 or later.

To authenticate a Docker client with artifact registry:

1. Authenticate with the GitLab CLI:

   glab auth login

   This command stores a GitLab credential on disk that glab can reference when you log in with the Docker CLI.

2. Log in with the Docker CLI:

   glab artifact-registry login --docker --registry <registry_host>

   For <registry_host>, use a bare hostname, like ar.example.com. This command registers glab as a Docker credential helper. Every request gets a fresh token, so you do not need to specify a token expiry time with the --duration flag.

To authenticate a Podman client with artifact registry:

1. Get a token and pass it to podman login:

   glab artifact-registry get-token |
     podman login <registry_host> --username __token__ --password-stdin

   You cannot refresh this token. Run the command again before it expires.

Configure your client

An image in a Docker repository is available at:

https://<registry_host>/<registry_handle>/container/<repository_name>/<image_name>:<tag>

Replace the following placeholders:

• <registry_host>: Enter the bare hostname from your repository’s setup instructions. To find it, go to your repository and select More actions > View setup instructions. Docker stores credentials by hostname, so use the bare hostname, such as ar.example.com.
• <registry_handle>: Enter your organization’s registry handle.
• <repository_name>: Enter the name of your repository name.
• <image_name>: Enter the image name in the repository.
• <tag>: Enter the image tag, such as latest.

The path segment is container for both Docker and OCI repositories. One set of endpoints serves both formats. docker and oci appear only in management API URLs.

Supported artifacts

Docker and Podman accept the following artifacts:

• Container image manifests that carry an image configuration.
• Manifest indexes, which is what a multi-platform build produces.
• Any manifest that carries a subject, which covers signatures, attestations, and other artifacts that refer to an image.
• cosign signatures and software bill of materials attestations.

A Docker repository rejects any artifacts that are not a container image. For example, a Helm chart, a WebAssembly module with an empty configuration, or Docker manifests that use schema 1.

Store artifacts that are not container images in an OCI repository instead. For details, see OCI artifacts in Artifact Registry.

Image names and path length

An image name:

• Uses lowercase letters and digits, with periods, underscores, and hyphens as separators.
• Can hold several segments separated by slashes, such as team/service/api. The entire string counts as one image name.

The full path, made up of the registry handle, the repository name, and the image name, cannot exceed 255 characters, and separator characters count toward that limit.

Tags

Pushing a tag that already exists moves the tag to the new manifest. Artifact Registry does not reject it. Tag listings are paginated. A listing returns 100 tags by default and up to 1,000 tags.

Limits

For the full list of limits, see Artifact Registry limits.

Delete an image

Deleting a manifest also deletes the tags that point at it. Deleting a manifest that another manifest references returns a 409 Conflict error. The response lists the manifests that refer to it. Delete those first.

For specific steps, see the Artifact Registry API.

Commands that do not work

• docker search against the registry returns nothing. Artifact Registry does not implement the catalog endpoint that lists repositories.