- Change the visibility of the Container Registry
- List registry repositories
- Get details of a single repository
- Delete registry repository
- List registry repository tags
- Get details of a registry repository tag
- Delete a registry repository tag
- Delete registry repository tags in bulk
- Instance-wide endpoints
Container Registry API
The use of CI_JOB_TOKEN
scoped to the current project was introduced in GitLab 13.12.
This is the API documentation of the GitLab Container Registry.
When the ci_job_token_scope
feature flag is enabled (it is disabled by default), you can use the below endpoints
from a CI/CD job, by passing the $CI_JOB_TOKEN
variable as the JOB-TOKEN
header.
The job token will only have access to its own project.
GitLab administrators with access to the GitLab Rails console can opt to enable it.
To enable it:
Feature.enable(:ci_job_token_scope)
To disable it:
Feature.disable(:ci_job_token_scope)
Change the visibility of the Container Registry
Introduced in GitLab 14.2.
This controls who can view the Container Registry.
PUT /projects/:id/
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the project accessible by the authenticated user. |
container_registry_access_level |
string | no | The desired visibility of the Container Registry. One of enabled (default), private , or disabled . |
Descriptions of the possible values for container_registry_access_level
:
-
enabled (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.
-
private: The Container Registry is visible only to project members with Reporter role or higher. This is similar to the behavior of a private project with Container Registry visibility set to enabled.
-
disabled: The Container Registry is disabled.
See the Container Registry visibility permissions for more details about the permissions that this setting grants to users.
curl --request PUT "https://gitlab.example.com/api/v4/projects/5/" \
--header 'PRIVATE-TOKEN: <your_access_token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"container_registry_access_level": "private"
}'
Example response:
{
"id": 5,
"name": "Project 5",
"container_registry_access_level": "private",
...
}
List registry repositories
Within a project
Get a list of registry repositories in a project.
GET /projects/:id/registry/repositories
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the project accessible by the authenticated user. |
tags |
boolean | no | If the parameter is included as true, each repository includes an array of "tags" in the response. |
tags_count |
boolean | no | If the parameter is included as true, each repository includes "tags_count" in the response (Introduced in GitLab 13.1). |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories"
Example response:
[
{
"id": 1,
"name": "",
"path": "group/project",
"project_id": 9,
"location": "gitlab.example.com:5000/group/project",
"created_at": "2019-01-10T13:38:57.391Z",
"cleanup_policy_started_at": "2020-01-10T15:40:57.391Z"
},
{
"id": 2,
"name": "releases",
"path": "group/project/releases",
"project_id": 9,
"location": "gitlab.example.com:5000/group/project/releases",
"created_at": "2019-01-10T13:39:08.229Z",
"cleanup_policy_started_at": "2020-08-17T03:12:35.489Z"
}
]
Within a group
Removed the tags
and tag_count
attributes in GitLab 15.0.
Get a list of registry repositories in a group.
GET /groups/:id/registry/repositories
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the group accessible by the authenticated user. |
curl --header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/groups/2/registry/repositories"
Example response:
[
{
"id": 1,
"name": "",
"path": "group/project",
"project_id": 9,
"location": "gitlab.example.com:5000/group/project",
"created_at": "2019-01-10T13:38:57.391Z",
"cleanup_policy_started_at": "2020-08-17T03:12:35.489Z",
},
{
"id": 2,
"name": "",
"path": "group/other_project",
"project_id": 11,
"location": "gitlab.example.com:5000/group/other_project",
"created_at": "2019-01-10T13:39:08.229Z",
"cleanup_policy_started_at": "2020-01-10T15:40:57.391Z",
}
]
Get details of a single repository
Introduced in GitLab 13.6.
Get details of a registry repository.
GET /registry/repositories/:id
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | The ID of the registry repository accessible by the authenticated user. |
tags |
boolean | no | If the parameter is included as true , the response includes an array of "tags" . |
tags_count |
boolean | no | If the parameter is included as true , the response includes "tags_count" . |
size |
boolean | no | If the parameter is included as true , the response includes "size" . This is the deduplicated size of all images within the repository. Deduplication eliminates extra copies of identical data. For example, if you upload the same image twice, the Container Registry stores only one copy. This field is only available on GitLab.com for repositories created after 2021-11-04 . |
curl --header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/registry/repositories/2?tags=true&tags_count=true&size=true"
Example response:
{
"id": 2,
"name": "",
"path": "group/project",
"project_id": 9,
"location": "gitlab.example.com:5000/group/project",
"created_at": "2019-01-10T13:38:57.391Z",
"cleanup_policy_started_at": "2020-08-17T03:12:35.489Z",
"tags_count": 1,
"tags": [
{
"name": "0.0.1",
"path": "group/project:0.0.1",
"location": "gitlab.example.com:5000/group/project:0.0.1"
}
],
"size": 2818413
}
Delete registry repository
Delete a repository in registry.
This operation is executed asynchronously and might take some time to get executed.
DELETE /projects/:id/registry/repositories/:repository_id
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user. |
repository_id |
integer | yes | The ID of registry repository. |
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/projects/5/registry/repositories/2"
List registry repository tags
Within a project
Get a list of tags for given registry repository.
GET /projects/:id/registry/repositories/:repository_id/tags
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the project accessible by the authenticated user. |
repository_id |
integer | yes | The ID of registry repository. |