Container registry

Use this API to manage the GitLab container registry: list the registry repositories in a project or a group, retrieve or delete individual repositories and their tags, and receive registry events.

To authenticate with these endpoints from a CI/CD job, pass the $CI_JOB_TOKEN variable as the JOB-TOKEN header. The job token only has access to the container registry of the project that created the pipeline.

Receives notifications from the container registry when an operation occurs

POST /api/v4/container_registry_event/events

This feature was introduced in GitLab 12.10

Responses

Code	Description	Schema
`200`	Success	—
`400`	Bad Request	—
`401`	Invalid Token	—

List all registry repositories for a group

GET /api/v4/groups/{id}/registry/repositories

Lists all registry repositories for a specified group.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the group
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesContainerRegistryRepository
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Group Not Found	—

List all registry repositories for a project

GET /api/v4/projects/{id}/registry/repositories

Lists all registry repositories for a specified project. Responses are paginated and return 20 results by default.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`
`tags` Query	Boolean	If `true`, includes an array of `tags` in the response Default: `false`
`tags_count` Query	Boolean	If `true`, includes `tags_count` in the response Default: `false`

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesContainerRegistryRepository
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Not Found	—

Delete registry repository

DELETE /api/v4/projects/{id}/registry/repositories/{repository_id}

Deletes a specified repository in the registry. This operation is executed asynchronously and might take some time to execute.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`repository_id` Path, required	Integer	ID of the container registry repository

Responses

Code	Description	Schema
`204`	Success	—
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Not Found	—

List all registry repository tags for a project

GET /api/v4/projects/{id}/registry/repositories/{repository_id}/tags

Lists all tags for a specified registry repository. Responses are paginated and return 20 results by default.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`repository_id` Path, required	Integer	ID of the container registry repository
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesContainerRegistryTag
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Not Found	—
`405`	Method Not Allowed	—

Delete multiple registry repository tags

DELETE /api/v4/projects/{id}/registry/repositories/{repository_id}/tags

Deletes multiple registry repository tags based on the specified criteria.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`repository_id` Path, required	Integer	ID of the container registry repository
`name_regex_delete` Query	String	RE2 regular expression of the tag names to delete. Specify `.*` to delete all tags. At least one of `name_regex`, `name_regex_delete` must be provided
`name_regex` Query	String	RE2 regular expression of the tag names to delete. Specify `.*` to delete all tags. Deprecated. Use `name_regex_delete` instead. At least one of `name_regex`, `name_regex_delete` must be provided
`name_regex_keep` Query	String	RE2 regular expression of the tag names to keep. Overrides any matches from `name_regex_delete`. Setting to `.*` results in a no-op
`keep_n` Query	Integer	Number of most recent tags with a matching name to keep
`older_than` Query	String	Delete tags older than this age, such as `1h`, `1d`, or `1month`

Responses

Code	Description	Schema
`204`	Success	—
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Not Found	—

Retrieve details of a registry repository tag

GET /api/v4/projects/{id}/registry/repositories/{repository_id}/tags/{tag_name}

Retrieves details of a specified registry repository tag.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`repository_id` Path, required	Integer	ID of the container registry repository
`tag_name` Path, required	String	Name of the tag

Responses

Code	Description	Schema
`200`	OK	APIEntitiesContainerRegistryTagDetails
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Not Found	—

Delete a registry repository tag

DELETE /api/v4/projects/{id}/registry/repositories/{repository_id}/tags/{tag_name}

Deletes a specified container registry repository tag.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`repository_id` Path, required	Integer	ID of the container registry repository
`tag_name` Path, required	String	Name of the tag

Responses

Code	Description	Schema
`204`	Success	—
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not Found	—

Retrieve details of a container registry repository

GET /api/v4/registry/repositories/{id}

Retrieves details of a specified container registry repository.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID of the repository
`tags` Query	Boolean	If `true`, includes an array of `tags` in the response Default: `false`
`tags_count` Query	Boolean	If `true`, includes `tags_count` in the response Default: `false`
`size` Query	Boolean	If `true`, response includes the deduplicated size of all images in the repository. Only available on GitLab.com for repositories created after `2021-11-04` Default: `false`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesContainerRegistryRepository
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Repository Not Found	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesContainerRegistryRepository

Property	Type	Description
`cleanup_policy_started_at`	String (date-time)	Example: `2020-08-17T03:12:35.489Z`
`created_at`	String (date-time)	Example: `2019-01-10T13:39:08.229Z`
`delete_api_path`	String	Example: `delete/api/path`
`id`	Integer (int64)	Example: `1`
`location`	String	Example: `gitlab.example.com/group/project/releases`
`name`	String	Example: `releases`
`path`	String	Example: `group/project/releases`
`project_id`	Integer (int64)	Example: `9`
`size`	Integer	Example: `12345`
`status`	String	Example: `delete_scheduled`
`tags`	APIEntitiesContainerRegistryTag	—
`tags_count`	Integer	Example: `3`

APIEntitiesContainerRegistryTag

Property	Type	Description
`location`	String	Example: `registry.dev/namespace1/project1/test_image_1:latest`
`name`	String	Example: `latest`
`path`	String	Example: `namespace1/project1/test_image_1:latest`

APIEntitiesContainerRegistryTagDetails

Property	Type	Description
`created_at`	String (date-time)	Example: `2022-01-10T13:39:08.229Z`
`digest`	String	Example: `shadigest`
`location`	String	Example: `registry.dev/namespace1/project1/test_image_1:latest`
`name`	String	Example: `latest`
`path`	String	Example: `namespace1/project1/test_image_1:latest`
`revision`	String	Example: `tagrevision`
`short_revision`	String	Example: `shortrevison`
`total_size`	Integer	Example: `3`

Receives notifications from the container registry when an operation occurs

List all registry repositories for a group

List all registry repositories for a project

Delete registry repository

List all registry repository tags for a project

Delete multiple registry repository tags

Retrieve details of a registry repository tag

Delete a registry repository tag

Retrieve details of a container registry repository

Schemas

APIEntitiesContainerRegistryRepository

APIEntitiesContainerRegistryTag

APIEntitiesContainerRegistryTagDetails

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC compliance report

Thank you

Error

Request partner program details

Request received

Error