• View the tags of a specific container image in the Container Registry

GitLab Container Registry

Searching by image repository name was introduced in GitLab 13.0.

You can use the integrated Container Registry to store container images for each GitLab project

To enable the Container Registry for your GitLab instance, see the administrator documentation .

If you pull Docker container images from Docker Hub, you can use the GitLab Dependency Proxy to avoid rate limits and speed up your pipelines. For more information about the Docker Registry, see https://docs.docker.com/registry/introduction/ .

View the Container Registry

You can view the Container Registry for a project or group.

1. On the top bar, select Main menu , and:
2. For a project, select Projects and find your project.
3. For a group, select Groups and find your group.
4. On the left sidebar, select Packages and registries > Container Registry .

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

Only members of the project or group can access the Container Registry for a private project. Container images downloaded from a private registry may be available to other users in a shared runner .

If a project is public, the Container Registry is also public.

View the tags of a specific container image in the Container Registry

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

1. On the top bar, select Main menu , and:
2. For a project, select Projects and find your project.
3. For a group, select Groups and find your group.
4. On the left sidebar, select Packages and registries > Container Registry .
5. 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), filter, and delete tags on this page. You can share a filtered view by copying the URL from your browser.

Use container images from the Container Registry

To download and run a container image hosted in the Container Registry:

1. On the top bar, select Main menu , and:
2. For a project, select Projects and find your project.
3. For a group, select Groups and find your group.
4. On the left sidebar, select Packages and registries > Container Registry .

5. Find the container image you want to work with and select Copy .

   

6. Use docker run with the copied link:

   docker run [options] registry.example.com/group/project/image [arguments]
   You must authenticate with the container registry to download
   container images from a private repository.

   For more information on running container images, see the Docker documentation .

   Naming convention for your container images

   Your container images must follow this naming convention:

   <registry URL>/<namespace>/<project>/<image>
   

   For example, if your project is gitlab.example.com/mynamespace/myproject , then your container image must be named gitlab.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 named myproject :

   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

   Moving or renaming existing Container Registry repositories is not supported after you have pushed container images. The container images are stored in a path that matches the repository path. To move or rename a repository with a Container Registry, you must delete all existing container images. Community suggestions to work around this known issue are shared in issue 18383 .

   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 top bar, select Main menu > Projects .
   2. On the left sidebar, select Settings > General .
   3. Expand the Visibility, project features, permissions section and disable Container Registry .
   4. Select Save changes .

   The Packages and registries > Container Registry entry is removed from the project’s sidebar.

   Change visibility of the Container Registry

   Introduced in GitLab 14.2.

   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, see Container Registry visibility permissions .

   1. On the top bar, select Main menu > Projects .
   2. On the left sidebar, select Settings > General .
   3. Expand the section Visibility, project features, permissions .

   4. Under Container Registry , select an option from the dropdown list:

      Everyone With Access (Default): The Container Registry is visible to everyone with access to the project. If the project is public, the Container Registry is also public. If the project is internal or private, the Container Registry is also internal or private.

      • Only Project Members : The Container Registry is visible only to project members with Reporter role or higher. This visibility is similar to the behavior of a private project with Container Registry visibility set to Everyone With Access .

   5. Select Save changes .

   Container Registry visibility permissions

   The ability to view the Container Registry and pull container images is controlled by the Container Registry’s visibility permissions. You can change the visibility through the visibility setting on the UI or the API . Other permissions such as updating the Container Registry and pushing or deleting container images are not affected by this setting. However, disabling the Container Registry disables all Container Registry operations.

   		Anonymous (Everyone on internet)	Guest	Reporter, Developer, Maintainer, Owner
   Public project with Container Registry visibility set to Everyone With Access (UI) or enabled (API)	View Container Registry and pull images	Yes	Yes	Yes
   Public project with Container Registry visibility set to Only Project Members (UI) or private (API)	View Container Registry and pull images	No	No	Yes
   Internal project with Container Registry visibility set to Everyone With Access (UI) or enabled (API)	View Container Registry and pull images	No	Yes	Yes
   Internal project with Container Registry visibility set to Only Project Members (UI) or private (API)	View Container Registry and pull images	No	No	Yes
   Private project with Container Registry visibility set to Everyone With Access (UI) or enabled (API)	View Container Registry and pull images	No	No	Yes
   Private project with Container Registry visibility set to Only Project Members (UI) or private (API)	View Container Registry and pull images	No	No	Yes
   Any project with Container Registry disabled	All operations on Container Registry	No	No	No

   Supported image types

   The Container Registry supports Docker V2 and Open Container Initiative (OCI) image formats.

   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.

   Help & feedback

   Docs

   Edit this page to fix an error or add an improvement in a merge request.
   Create an issue to suggest an improvement to this page.
   

   Product

   Create an issue if there's something you don't like about this feature.
   Propose functionality by submitting a feature request.
   Join First Look to help shape new features.

   Feature availability and product trials

   View pricing to see all GitLab tiers and features, or to upgrade.
   Try GitLab for free with access to all features for 30 days.
   

   Get Help

   If you didn't find what you were looking for, search the docs .
   If you want help with something specific and could use community support, post on the GitLab forum .
   For problems setting up or using this feature (depending on your GitLab subscription).
   

   Request support