1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
---
stage: Package
group: Container Registry
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# GitLab container registry
DETAILS:
**Tier:** Free, Premium, Ultimate
**Offering:** GitLab.com, Self-managed, GitLab Dedicated
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](../../../administration/packages/container_registry.md).
NOTE:
If you pull container images from Docker Hub, you can use the
[GitLab Dependency Proxy](../dependency_proxy/index.md#use-the-dependency-proxy-for-docker-images) to avoid
rate limits and speed up your pipelines.
## View the container registry
You can view the container registry for a project or group.
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Deploy > Container Registry**.
You can search, sort, filter, and [delete](delete_container_registry_images.md#use-the-gitlab-ui)
your 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 registry **Tag Details** page to view a list of tags associated with a given container image:
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Deploy > Container Registry**.
1. 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](delete_container_registry_images.md#use-the-gitlab-ui)
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 left sidebar, select **Search or go to** and find your project or group.
1. Select **Deploy > Container Registry**.
1. Find the container image you want to work with and select **Copy image path** （**{copy-to-clipboard}**）.
1. Use `docker run` with the copied link:
```shell
docker run [options] registry.example.com/group/project/image [arguments]
```
NOTE:
You must [authenticate with the container registry](authenticate_with_container_registry.md) to download
container images from a private repository.
For more information on running container images, see the [Docker documentation](https://docs.docker.com/get-started/).
## Naming convention for your container images
Your container images must follow this naming convention:
```plaintext
<registry server>/<namespace>/<project>[/<optional path>]
```
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`:
```plaintext
registry.example.com/mynamespace/myproject:some-tag
```
```plaintext
registry.example.com/mynamespace/myproject/image:latest
```
```plaintext
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
[rename](../../project/working_with_projects.md#rename-a-repository) or [move](../../project/settings/migrate_projects.md)
the entire project.
Renaming projects with populated container repositories is only supported on GitLab.com.
On a self-managed instance, you can delete all container images before moving or renaming
a group or project. Alternatively, [issue 18383](https://gitlab.com/gitlab-org/gitlab/-/issues/18383#possible-workaround)
contains community suggestions to work around this limitation. [Epic 9459](https://gitlab.com/groups/gitlab-org/-/epics/9459)
proposes adding support for moving projects and groups with container repositories
to self-managed GitLab.
## 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, select **Search or go to** and find your project.
1. Select **Settings > General**.
1. Expand the **Visibility, project features, permissions** section
and disable **Container registry**.
1. Select **Save changes**.
The **Deploy > 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,
see [Container registry visibility permissions](#container-registry-visibility-permissions).
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Settings > General**.
1. Expand the section **Visibility, project features, permissions**.
1. 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
at least the Reporter role. This visibility is similar to the behavior of a private project with Container
Registry visibility set to **Everyone With Access**.
1. 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](#change-visibility-of-the-container-registry)
or the [API](../../../api/container_registry.md#change-the-visibility-of-the-container-registry).
[Other permissions](../../permissions.md) 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<br/>(Everyone on internet) | Guest | Reporter, Developer, Maintainer, Owner |
|-------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|--------------------------------------|-------|----------------------------------------|
| Public project with container registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View container registry <br/> and pull images | Yes | Yes | Yes |
| Public project with container registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View container registry <br/> and pull images | No | No | Yes |
| Internal project with container registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View container registry <br/> and pull images | No | Yes | Yes |
| Internal project with container registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View container registry <br/> and pull images | No | No | Yes |
| Private project with container registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View container registry <br/> and pull images | No | No | Yes |
| Private project with container registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View container registry <br/> and pull images | No | No | Yes |
| Any project with container registry `disabled` | All operations on container registry | No | No | No |
## Supported image types
> - OCI conformance [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10345) in GitLab 16.6.
The container registry supports the [Docker V2](https://distribution.github.io/distribution/spec/manifest-v2-2/)
and [Open Container Initiative (OCI)](https://github.com/opencontainers/image-spec/blob/main/spec.md)
image formats. Additionally, the container registry [conforms to the OCI distribution specification](https://conformance.opencontainers.org/#gitlab-container-registry).
OCI support means that you can host OCI-based image formats in the registry, such as [Helm 3+ chart packages](https://helm.sh/docs/topics/registries/). There is no distinction between image formats in the GitLab [API](../../../api/container_registry.md) and the UI. [Issue 38047](https://gitlab.com/gitlab-org/gitlab/-/issues/38047) addresses this distinction, starting with Helm.
## Container image signatures
> - Container image signature display [introduced](https://gitlab.com/groups/gitlab-org/-/epics/7856) in GitLab 17.1.
In the GitLab container registry, you can use the [OCI 1.1 manifest `subject` field](https://github.com/opencontainers/image-spec/blob/v1.1.0/manifest.md)
to associate container images with [Cosign signatures](../../../ci/yaml/signing_examples.md).
You can then view signature information alongside its associated container image without having to
search for that signature's tag.
When [viewing a container image's tags](#view-the-tags-of-a-specific-container-image-in-the-container-registry), you see an icon displayed
next 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 self-managed GitLab instances, you need a
[GitLab container registry configured with a metadata database](../../../administration/packages/container_registry_metadata_database.md)
to display signatures.
### Sign container images with OCI referrer data
To add referrer data to signatures using Cosign, you must:
- Set the `COSIGN_EXPERIMENTAL` environment variable to `1`.
- Add `--registry-referrers-mode oci-1-1` to the signature command.
For example:
```shell
COSIGN_EXPERIMENTAL=1 cosign sign --registry-referrers-mode oci-1-1 <container image>
```
NOTE:
While the GitLab container registry supports the OCI 1.1 manifest `subject` field, it does not fully
implement the [OCI 1.1 Referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#listing-referrers).
|
