2019-01-10 09:22:58 -05:00
# Container Registry API
2019-09-18 10:02:45 -04:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/55978) in GitLab 11.8.
2019-02-08 10:13:01 -05:00
2019-09-17 08:06:48 -04:00
This is the API docs of the [GitLab Container Registry ](../user/packages/container_registry/index.md ).
2019-01-15 13:02:47 -05:00
2019-01-10 09:22:58 -05:00
## List registry repositories
2019-08-05 16:00:50 -04:00
### Within a project
2019-01-10 09:22:58 -05:00
Get a list of registry repositories in a project.
2020-02-27 04:09:01 -05:00
```plaintext
2019-01-10 09:22:58 -05:00
GET /projects/:id/registry/repositories
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2019-08-05 16:00:50 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) accessible by the authenticated user. |
| `tags` | boolean | no | If the param is included as true, each repository will include an array of `"tags"` in the response. |
2019-01-10 09:22:58 -05:00
2020-01-30 10:09:15 -05:00
```shell
2019-01-10 09:22:58 -05:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/registry/repositories"
```
Example response:
```json
[
{
"id": 1,
"name": "",
"path": "group/project",
2019-08-05 16:00:50 -04:00
"project_id": 9,
2019-01-10 09:22:58 -05:00
"location": "gitlab.example.com:5000/group/project",
"created_at": "2019-01-10T13:38:57.391Z"
},
{
"id": 2,
"name": "releases",
"path": "group/project/releases",
2019-08-05 16:00:50 -04:00
"project_id": 9,
2019-01-10 09:22:58 -05:00
"location": "gitlab.example.com:5000/group/project/releases",
"created_at": "2019-01-10T13:39:08.229Z"
}
]
```
2019-08-05 16:00:50 -04:00
### Within a group
Get a list of registry repositories in a group.
2020-02-27 04:09:01 -05:00
```plaintext
2019-08-05 16:00:50 -04:00
GET /groups/:id/registry/repositories
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group ](README.md#namespaced-path-encoding ) accessible by the authenticated user. |
| `tags` | boolean | no | If the param is included as true, each repository will include an array of `"tags"` in the response. |
2020-01-30 10:09:15 -05:00
```shell
2019-08-05 16:00:50 -04:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/2/registry/repositories?tags=1"
```
Example response:
```json
[
{
"id": 1,
"name": "",
"path": "group/project",
"project_id": 9,
"location": "gitlab.example.com:5000/group/project",
"created_at": "2019-01-10T13:38:57.391Z",
"tags": [
{
"name": "0.0.1",
"path": "group/project:0.0.1",
"location": "gitlab.example.com:5000/group/project:0.0.1"
}
]
},
{
"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",
"tags": [
{
"name": "0.0.1",
"path": "group/other_project:0.0.1",
"location": "gitlab.example.com:5000/group/other_project:0.0.1"
},
{
"name": "0.0.2",
"path": "group/other_project:0.0.2",
"location": "gitlab.example.com:5000/group/other_project:0.0.2"
},
{
"name": "latest",
"path": "group/other_project:latest",
"location": "gitlab.example.com:5000/group/other_project:latest"
}
]
}
]
```
2019-01-10 09:22:58 -05:00
## Delete registry repository
2019-02-08 10:13:01 -05:00
Delete a repository in registry.
2019-01-10 09:22:58 -05:00
2019-01-15 13:02:47 -05:00
This operation is executed asynchronously and might take some time to get executed.
2019-01-10 09:22:58 -05:00
2020-02-27 04:09:01 -05:00
```plaintext
2019-01-10 09:22:58 -05:00
DELETE /projects/:id/registry/repositories/:repository_id
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2019-01-15 13:02:47 -05:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user. |
| `repository_id` | integer | yes | The ID of registry repository. |
2019-01-10 09:22:58 -05:00
2020-01-30 10:09:15 -05:00
```shell
2019-01-15 13:02:47 -05:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2"
2019-01-10 09:22:58 -05:00
```
2020-02-04 07:09:00 -05:00
## List registry repository tags
2019-01-10 09:22:58 -05:00
2019-08-05 16:00:50 -04:00
### Within a project
2019-01-10 09:22:58 -05:00
Get a list of tags for given registry repository.
2020-02-27 04:09:01 -05:00
```plaintext
2019-01-10 09:22:58 -05:00
GET /projects/:id/registry/repositories/:repository_id/tags
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2019-08-05 16:00:50 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) accessible by the authenticated user. |
2019-01-15 13:02:47 -05:00
| `repository_id` | integer | yes | The ID of registry repository. |
2019-01-10 09:22:58 -05:00
2020-01-30 10:09:15 -05:00
```shell
2019-01-10 09:22:58 -05:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags"
```
Example response:
```json
[
{
"name": "A",
"path": "group/project:A",
"location": "gitlab.example.com:5000/group/project:A"
},
{
"name": "latest",
"path": "group/project:latest",
"location": "gitlab.example.com:5000/group/project:latest"
}
]
```
2020-02-04 07:09:00 -05:00
## Get details of a registry repository tag
2019-01-10 09:22:58 -05:00
2019-01-15 13:02:47 -05:00
Get details of a registry repository tag.
2019-01-10 09:22:58 -05:00
2020-02-27 04:09:01 -05:00
```plaintext
2019-01-10 09:22:58 -05:00
GET /projects/:id/registry/repositories/:repository_id/tags/:tag_name
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2019-08-05 16:00:50 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) accessible by the authenticated user. |
2019-01-15 13:02:47 -05:00
| `repository_id` | integer | yes | The ID of registry repository. |
| `tag_name` | string | yes | The name of tag. |
2019-01-10 09:22:58 -05:00
2020-01-30 10:09:15 -05:00
```shell
2019-01-10 09:22:58 -05:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0"
```
Example response:
```json
{
"name": "v10.0.0",
"path": "group/project:latest",
"location": "gitlab.example.com:5000/group/project:latest",
"revision": "e9ed9d87c881d8c2fd3a31b41904d01ba0b836e7fd15240d774d811a1c248181",
"short_revision": "e9ed9d87c",
"digest": "sha256:c3490dcf10ffb6530c1303522a1405dfaf7daecd8f38d3e6a1ba19ea1f8a1751",
"created_at": "2019-01-06T16:49:51.272+00:00",
"total_size": 350224384
}
```
2020-02-04 07:09:00 -05:00
## Delete a registry repository tag
2019-01-10 09:22:58 -05:00
2019-01-15 13:02:47 -05:00
Delete a registry repository tag.
2019-01-10 09:22:58 -05:00
2020-02-27 04:09:01 -05:00
```plaintext
2019-01-10 09:22:58 -05:00
DELETE /projects/:id/registry/repositories/:repository_id/tags/:tag_name
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2019-01-15 13:02:47 -05:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user. |
| `repository_id` | integer | yes | The ID of registry repository. |
| `tag_name` | string | yes | The name of tag. |
2019-01-10 09:22:58 -05:00
2020-01-30 10:09:15 -05:00
```shell
2019-01-15 13:02:47 -05:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0"
```
2019-06-20 05:24:02 -04:00
This action does not delete blobs. In order to delete them and recycle disk space,
[run the garbage collection ](https://docs.gitlab.com/omnibus/maintenance/README.html#removing-unused-layers-not-referenced-by-manifests ).
2020-02-04 07:09:00 -05:00
## Delete registry repository tags in bulk
2019-01-15 13:02:47 -05:00
2020-02-04 07:09:00 -05:00
Delete registry repository tags in bulk based on given criteria.
2019-01-15 13:02:47 -05:00
2020-02-27 04:09:01 -05:00
```plaintext
2019-01-15 13:02:47 -05:00
DELETE /projects/:id/registry/repositories/:repository_id/tags
2019-01-10 09:22:58 -05:00
```
2019-01-15 13:02:47 -05:00
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user. |
| `repository_id` | integer | yes | The ID of registry repository. |
2020-03-02 16:08:01 -05:00
| `name_regex` | string | no | The [re2 ](https://github.com/google/re2/wiki/Syntax ) regex of the name to delete. To delete all tags specify `.*` . **Note:** `name_regex` is deprecated in favor of `name_regex_delete` .|
| `name_regex_delete` | string | yes | The [re2 ](https://github.com/google/re2/wiki/Syntax ) regex of the name to delete. To delete all tags specify `.*` .|
| `name_regex_keep` | string | no | The [re2 ](https://github.com/google/re2/wiki/Syntax ) regex of the name to keep. This value will override any matches from `name_regex_delete` . Note: setting to `.*` will result in a no-op. |
2019-01-15 13:02:47 -05:00
| `keep_n` | integer | no | The amount of latest tags of given name to keep. |
| `older_than` | string | no | Tags to delete that are older than the given time, written in human readable form `1h` , `1d` , `1month` . |
This API call performs the following operations:
1. It orders all tags by creation date. The creation date is the time of the
manifest creation, not the time of tag push.
2020-03-02 16:08:01 -05:00
1. It removes only the tags matching the given `name_regex_delete` (or deprecated `name_regex` ), keeping any that match `name_regex_keep` .
2019-01-15 13:02:47 -05:00
1. It never removes the tag named `latest` .
1. It keeps N latest matching tags (if `keep_n` is specified).
1. It only removes tags that are older than X amount of time (if `older_than` is specified).
1. It schedules the asynchronous job to be executed in the background.
These operations are executed asynchronously and it might
take time to get executed. You can run this at most
once an hour for a given container repository.
2019-06-20 05:24:02 -04:00
This action does not delete blobs. In order to delete them and recycle disk space,
[run the garbage collection ](https://docs.gitlab.com/omnibus/maintenance/README.html#removing-unused-layers-not-referenced-by-manifests ).
2019-01-15 13:02:47 -05:00
NOTE: **Note:**
2019-09-19 07:50:12 -04:00
Since GitLab 12.4, individual tags are deleted.
For more details, see the [discussion ](https://gitlab.com/gitlab-org/gitlab/issues/15737 ).
2019-01-15 13:02:47 -05:00
Examples:
1. Remove tag names that are matching the regex (Git SHA), keep always at least 5,
and remove ones that are older than 2 days:
2020-01-30 10:09:15 -05:00
```shell
2020-03-02 16:08:01 -05:00
curl --request DELETE --data 'name_regex_delete=[0-9a-z]{40}' --data 'keep_n=5' --data 'older_than=2d' --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags"
2019-01-15 13:02:47 -05:00
```
2019-07-18 22:20:32 -04:00
1. Remove all tags, but keep always the latest 5:
2019-01-15 13:02:47 -05:00
2020-01-30 10:09:15 -05:00
```shell
2020-03-02 16:08:01 -05:00
curl --request DELETE --data 'name_regex_delete=.*' --data 'keep_n=5' --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags"
```
1. Remove all tags, but keep always tags beginning with `stable` :
```shell
curl --request DELETE --data 'name_regex_delete=.*' --data 'name_regex_keep=stable.*' --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags"
2019-01-15 13:02:47 -05:00
```
2019-07-18 22:20:32 -04:00
1. Remove all tags that are older than 1 month:
2019-01-15 13:02:47 -05:00
2020-01-30 10:09:15 -05:00
```shell
2020-03-02 16:08:01 -05:00
curl --request DELETE --data 'name_regex_delete=.*' --data 'older_than=1month' --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags"
2019-01-15 13:02:47 -05:00
```