OCI artifacts in Artifact Registry

An Open Container Initiative (OCI) repository in Artifact Registry stores any OCI artifact, including ones that are not container images. It uses the same endpoints as a Docker repository. The difference is what it accepts on push.

Supported clients

• oras
• Docker CLI
• Podman

Authenticate

Prerequisites:

• The GitLab CLI, version 1.115.0 or later.

To authenticate with the Docker CLI:

1. Authenticate with the GitLab CLI:

   shell

   glab auth login

   This command stores a GitLab credential that the Docker credential helper uses. The helper ignores the GITLAB_TOKEN environment variable, so run this command even if GITLAB_TOKEN is set.

2. Run the following command:

   shell

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

   For <registry_host>, use a bare hostname, not a URL. This registers glab as a Docker credential helper, so every pull and push gets a fresh token. --duration does not apply, because the helper gets a new token each time.

To authenticate with oras or Podman:

1. Check that the GitLab CLI can authenticate:

   shell

   glab auth status

   glab artifact-registry get-token uses the GITLAB_TOKEN environment variable if it is set. Otherwise, it uses the credential that glab auth login stores. If glab auth status does not report that you are logged in, authenticate with the GitLab CLI:

   shell

   glab auth login

2. Get a token and pass it to the client. glab artifact-registry login has no flag for oras or Podman.

   shell

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

   For Podman, replace oras login with podman login. Nothing refreshes this token. Run the command again before it expires.

Configure your client

An artifact in an OCI repository is available at:

<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.
• <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.

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 OCI repository, or a virtual OCI 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:

  shell

  docker pull <registry_host>/<registry_handle>/container/<repository_name>/<image_name>:<tag>

  For Podman, run podman pull with 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:

  shell

  docker pull ar.example.com/acme/container/my-repo/library/alpine:latest

• Pull an image by digest:

  shell

  docker pull ar.example.com/acme/container/my-repo/library/alpine@sha256:<digest>

• Pull an image in a Dockerfile:

  dockerfile

  FROM ar.example.com/acme/container/my-repo/library/alpine:latest

How an OCI repository differs from a Docker repository

• An OCI repository accepts any manifest type, including artifacts that carry no image configuration and refer to nothing.
• A Docker repository accepts only image manifests and manifests that refer to an image. For details, see Docker images in Artifact Registry.
• Both reject Docker manifest schema 1.
• The format is fixed when you create a repository, so you cannot convert one to the other. Create a new repository instead.
• Choose an OCI repository for Helm charts, WebAssembly modules, machine learning models, and other artifacts that are not container images.

Image names and path length

• A name uses lowercase letters and digits, with periods, underscores, and hyphens as separators.
• A name can hold several segments separated by slashes. The whole thing counts as one name.
• The full path, made up of the registry handle, the repository name, and the artifact name, cannot be longer than 255 characters. Separator characters count.

Limits

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

Deleting artifacts

• Deleting a manifest also deletes the tags that point at it.
• A manifest that another manifest references returns 409. Delete the referencing manifests first.

For specific steps, see the Artifact Registry API.

Remote and virtual repositories

An OCI remote repository proxies and caches an upstream registry, the same as a Docker remote repository.

You can create and delete a virtual OCI repository, add Docker or OCI upstreams to it, and pull images through it.

For details, see Artifact Registry formats.