Docker images in Artifact Registry
- Tier: Premium, Ultimate
- Offering: GitLab.com
- Status: Beta
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:
-
Authenticate with the GitLab CLI:
glab auth loginThis command stores a GitLab credential that the Docker credential helper uses. The helper ignores the
GITLAB_TOKENenvironment variable, so run this command even ifGITLAB_TOKENis set. -
Log in with the Docker CLI:
glab artifact-registry login --docker --registry <registry_host>For
<registry_host>, use a bare hostname, likear.example.com. This command registersglabas a Docker credential helper. Every request gets a fresh token, so you do not need to specify a token expiry time with the--durationflag.
To authenticate a Podman client with artifact registry:
-
Check that the GitLab CLI can authenticate:
glab auth statusglab artifact-registry get-tokenuses theGITLAB_TOKENenvironment variable if it is set. Otherwise, it uses the credential thatglab auth loginstores. Ifglab auth statusdoes not report that you are logged in, authenticate with the GitLab CLI:glab auth login -
Get a token and pass it to
podman login:glab artifact-registry get-token | podman login <registry_host> --username __token__ --password-stdinYou 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 asar.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 aslatest.
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.
Pull images through a remote or virtual repository
Pull images through a remote or virtual repository to fetch them from upstream registries, like Docker Hub, through artifact registry.
Prerequisites:
- A remote Docker repository, or a virtual Docker repository with at least one upstream.
- A Docker CLI or Podman client authenticated with the registry host.
To pull an image:
-
Run the pull command with the image path in the repository:
docker pull <registry_host>/<registry_handle>/container/<repository_name>/<image_name>:<tag>For Podman, run
podman pullwith the same image path.
For images from Docker Hub, use the full image name.
Official images need the library/ prefix, such as library/alpine.
For example, for a repository named my-repo, with the registry host ar.example.com and the
registry handle acme:
-
Pull an image by its tag:
docker pull ar.example.com/acme/container/my-repo/library/alpine:latest -
Pull an image by digest:
docker pull ar.example.com/acme/container/my-repo/library/alpine@sha256:<digest> -
Pull an image in a
Dockerfile:FROM ar.example.com/acme/container/my-repo/library/alpine:latest
Use an image in a CI/CD job
The availability of this feature is controlled by a feature flag. For more information, see the history.
A CI/CD job can use an image from a Docker repository in image: or services: without
DOCKER_AUTH_CONFIG. GitLab gives the runner a credential for the registry host, and the
runner pulls the image as the job’s user before the job script starts. The job’s user is the
user who triggered the pipeline, or who started or retried the job.
Prerequisites:
- The job’s user must be a member of the project’s organization.
- The job’s user must have the Artifact Viewer role or higher on the repository.
- The runner must use an executor other than Kubernetes, such as the Docker executor.
To use an image in a job:
-
In your
.gitlab-ci.ymlfile, name the image with the registry host exactly as your repository’s setup instructions show it:test: image: ar.example.com/acme/container/my-repo/my-image:latest services: - name: ar.example.com/acme/container/my-repo/postgres:17 alias: postgres script: - ./run-tests.sh
The runner matches the credential to an image by its host and port. An image that names the host differently, for example with a port the setup instructions do not show, gets no credential.
If DOCKER_AUTH_CONFIG has an entry for the same host, the runner uses that entry instead.
When a job gets no credential
The job gets no credential when:
- The job’s user is not a member of the project’s organization. For example, the pipeline of a merge request from a fork whose author is outside the organization, a scheduled pipeline whose owner left the organization, or a service account created in another organization.
- The image is in another organization’s registry. A job gets a credential only for its project’s organization.
- The runner uses the Kubernetes executor, or does not report its executor.
In these cases, the pull of a private image fails before the job script runs. To pull the image,
set DOCKER_AUTH_CONFIG,
or on Kubernetes, use the service account’s image pull secrets.
If the job’s user has no role on the repository, the job gets a credential, but the pull is refused and the job fails before its script runs. The job shows a runner failure, not an authentication error.
Cached images on shared runners
Artifact registry checks access when a runner pulls an image, not when the runner reuses a copy it
pulled earlier. On a runner with the if-not-present pull policy, a job can start from an image
an earlier job pulled, whatever the access of its own user. For more information, see
usage of private Docker images with if-not-present pull policy.
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.
cosignsignatures 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.
Manifest attribution
A manifest of a hosted repository records who pushed it and, when a CI/CD job pushed it, which job:
created_by: the GitLab user ID of the user who pushed the manifest.project_id,git_commit_sha,pipeline_id, andjob_id: the project, commit, pipeline, and job of the CI/CD job that pushed the manifest.
Attribution works as follows:
- Only a push with a token that GitLab exchanged from a CI/CD ID token records the four build fields.
Other credentials, including
CI_JOB_TOKEN, leave them empty. - The four build fields are recorded together or not at all. A job that sends values the registry cannot store leaves all four empty, and the push still succeeds.
- The first push sets the values, and they never change while the manifest exists. Pushing the same manifest again succeeds and changes nothing, and moving a tag to a manifest that already exists is not a push of a new manifest.
- A manifest created before the registry recorded attribution, and a manifest of a remote repository, has no attribution.
Limits
| Limit | Value |
|---|---|
| Blob size | 50 GB |
| Manifest size | 4 MB |
| References per manifest | 200 |
| Manifests per image | 25,000 |
| Tags per manifest | 1,000 |
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.
On a hosted repository, a delete is permanent and can’t be undone.
For specific steps, see the Artifact Registry API.
Commands that do not work
docker searchagainst the registry returns nothing. Artifact Registry does not implement the catalog endpoint that lists repositories.