GitLab container registry

You can use the integrated container registry to store container images for each GitLab project.

An administrator must enable the container registry for your GitLab instance. For more information,seeGitLab container registry administration.

View the container registry

You can view the container registry for a project or group.

1. On the left sidebar, selectSearch or go to and find your project or group.
2. SelectDeploy >Container Registry.

You can search, sort, filter, anddeleteyour container images. You can share a filtered view by copying the URL from your browser.

View the tags of a specific container image in the container registry

You can use the container registryTag Details page to view a list of tags associated with a given container image:

1. On the left sidebar, selectSearch or go to and find your project or group.
2. SelectDeploy >Container Registry.
3. Select your container image.

You can view details about each tag, such as when it was published, how much storage it consumes,and the manifest and configuration digests.

You can search, sort (by tag name), and delete tags on this page.You can share a filtered view by copying the URL from your browser.

Storage usage

View container registry storage usage to track and manage the size of your container repositories across projects and groups.

For more information, seeView container registry usage.

Use container images from the container registry

To download and run a container image hosted in the container registry:

1. On the left sidebar, selectSearch or go to and find your project or group.

2. SelectDeploy >Container Registry.

3. Find the container image you want to work with and selectCopy image path （）.

4. Usedocker run with the copied link:

   docker run[options] registry.example.com/group/project/image[arguments]

Naming convention for your container images

Your container images must follow this naming convention:

<registry server>/<namespace>/<project>[/<optional path>]

For example, if your project isgitlab.example.com/mynamespace/myproject,then your container image must be namedgitlab.example.com/mynamespace/myproject.

You can append additional names to the end of a container image name, up to two levels deep.

For example, these are all valid names for container images in the project namedmyproject:

registry.example.com/mynamespace/myproject:some-tag

registry.example.com/mynamespace/myproject/image:latest

registry.example.com/mynamespace/myproject/my/image:rc1

Move or rename container registry repositories

The path of a container repository always matches the related project’s repository path,so renaming or moving only the container registry is not possible. Instead, you can either:

• Rename the project’s repository.
• Transfer the project.

Renaming projects with populated container repositories is only supported on GitLab.com.

On a GitLab Self-Managed instance, you can delete all container images before moving or renaminga group or project. Alternatively,issue 18383contains community suggestions to work around this limitation.Epic 9459proposes adding support for moving projects and groups with container repositoriesto GitLab Self-Managed.

Disable the container registry for a project

The container registry is enabled by default.

You can, however, remove the container registry for a project:

1. On the left sidebar, selectSearch or go to and find your project.
2. SelectSettings >General.
3. Expand theVisibility, project features, permissions sectionand disableContainer registry.
4. SelectSave changes.

TheDeploy >Container Registry entry is removed from the project’s sidebar.

Change visibility of the container registry

By default, the container registry is visible to everyone with access to the project.You can, however, change the visibility of the container registry for a project.

For more information about the permissions that this setting grants to users,seeContainer registry visibility permissions.

1. On the left sidebar, selectSearch or go to and find your project.

2. SelectSettings >General.

3. Expand the sectionVisibility, project features, permissions.

4. UnderContainer registry, select an option from the dropdown list:

   • Everyone With Access (Default): The container registry is visible to everyone with accessto the project. If the project is public, the container registry is also public. If the projectis internal or private, the container registry is also internal or private.

   • Only Project Members: The container registry is visible only to project members withat least the Reporter role. This visibility is similar to the behavior of a private project with ContainerRegistry visibility set toEveryone With Access.

5. SelectSave changes.

Container registry visibility permissions

The ability to view the container registry and pull container images is controlled by the container registry’svisibility permissions. You can change the visibility through the visibility setting on the UIor theAPI.

Other permissions, such as updating the container registry and pushing or deleting container images, are not affected bythis setting. However, disabling the container registry disables all container registry operations. For more information,seeRoles and permissions.

Supported image types

The container registry supports theDocker V2andOpen Container Initiative (OCI)image formats. Additionally, the container registryconforms to the OCI distribution specification.

OCI support means that you can host OCI-based image formats in the registry, such as Helm 3+ chart packages. There is no distinction between image formats in the GitLab API and the UI.Issue 38047 addresses this distinction, starting with Helm.

Container image signatures

In the GitLab container registry, you can use theOCI 1.1 manifestsubject fieldto associate container images withCosign signatures.You can then view signature information alongside its associated container image without having tosearch for that signature’s tag.

When viewing a container image’s tags, you see an icon displayednext to each tag that has an associated signature. To see the details of the signature, select the icon.

Prerequisites:

• To sign container images, Cosign v2.0 or later.
• For GitLab Self-Managed, you need a GitLab containerregistry configured with a metadata databaseto display signatures. For more information, seecontainer registry metadata database.

Sign container images with OCI referrer data

To add referrer data to signatures using Cosign, you must:

• Set theCOSIGN_EXPERIMENTAL environment variable to1.
• Add--registry-referrers-mode oci-1-1 to the signature command.

For example:

COSIGN_EXPERIMENTAL=1 cosign sign --registry-referrers-mode oci-1-1 <container image>