debian-mirror-gitlab/doc/api/container_registry.md

304 lines
11 KiB
Markdown
Raw Normal View History

2020-07-28 23:09:34 +05:30
---
stage: Package
group: Package
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
2019-03-02 22:35:43 +05:30
# Container Registry API
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55978) in GitLab 11.8.
2019-03-02 22:35:43 +05:30
2019-12-04 20:38:33 +05:30
This is the API docs of the [GitLab Container Registry](../user/packages/container_registry/index.md).
2019-03-02 22:35:43 +05:30
## List registry repositories
2019-10-12 21:52:04 +05:30
### Within a project
2019-03-02 22:35:43 +05:30
Get a list of registry repositories in a project.
2020-04-08 14:13:33 +05:30
```plaintext
2019-03-02 22:35:43 +05:30
GET /projects/:id/registry/repositories
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2019-10-12 21:52:04 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) accessible by the authenticated user. |
2021-01-03 14:25:43 +05:30
| `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](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/32141) in GitLab 13.1). |
2019-03-02 22:35:43 +05:30
2020-03-13 15:44:24 +05:30
```shell
2019-03-02 22:35:43 +05:30
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-10-12 21:52:04 +05:30
"project_id": 9,
2019-03-02 22:35:43 +05:30
"location": "gitlab.example.com:5000/group/project",
2021-01-03 14:25:43 +05:30
"created_at": "2019-01-10T13:38:57.391Z",
"cleanup_policy_started_at": "2020-01-10T15:40:57.391Z"
2019-03-02 22:35:43 +05:30
},
{
"id": 2,
"name": "releases",
"path": "group/project/releases",
2019-10-12 21:52:04 +05:30
"project_id": 9,
2019-03-02 22:35:43 +05:30
"location": "gitlab.example.com:5000/group/project/releases",
2021-01-03 14:25:43 +05:30
"created_at": "2019-01-10T13:39:08.229Z",
"cleanup_policy_started_at": "2020-08-17T03:12:35.489Z"
2019-03-02 22:35:43 +05:30
}
]
```
2019-10-12 21:52:04 +05:30
### Within a group
Get a list of registry repositories in a group.
2020-04-08 14:13:33 +05:30
```plaintext
2019-10-12 21:52:04 +05:30
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. |
2021-01-03 14:25:43 +05:30
| `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](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/32141) in GitLab 13.1). |
2019-10-12 21:52:04 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/2/registry/repositories?tags=1&tags_count=true"
2019-10-12 21:52:04 +05:30
```
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",
2021-01-03 14:25:43 +05:30
"cleanup_policy_started_at": "2020-08-17T03:12:35.489Z",
2020-06-23 00:09:42 +05:30
"tags_count": 1,
2019-10-12 21:52:04 +05:30
"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",
2021-01-03 14:25:43 +05:30
"cleanup_policy_started_at": "2020-01-10T15:40:57.391Z",
2020-06-23 00:09:42 +05:30
"tags_count": 3,
2019-10-12 21:52:04 +05:30
"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-03-02 22:35:43 +05:30
## Delete registry repository
Delete a repository in registry.
This operation is executed asynchronously and might take some time to get executed.
2020-04-08 14:13:33 +05:30
```plaintext
2019-03-02 22:35:43 +05:30
DELETE /projects/:id/registry/repositories/:repository_id
```
| 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-13 15:44:24 +05:30
```shell
2019-03-02 22:35:43 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2"
```
2020-03-13 15:44:24 +05:30
## List registry repository tags
2019-03-02 22:35:43 +05:30
2019-10-12 21:52:04 +05:30
### Within a project
2019-03-02 22:35:43 +05:30
Get a list of tags for given registry repository.
2020-04-08 14:13:33 +05:30
```plaintext
2019-03-02 22:35:43 +05:30
GET /projects/:id/registry/repositories/:repository_id/tags
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2019-10-12 21:52:04 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) accessible by the authenticated user. |
2019-03-02 22:35:43 +05:30
| `repository_id` | integer | yes | The ID of registry repository. |
2020-03-13 15:44:24 +05:30
```shell
2019-03-02 22:35:43 +05:30
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-03-13 15:44:24 +05:30
## Get details of a registry repository tag
2019-03-02 22:35:43 +05:30
Get details of a registry repository tag.
2020-04-08 14:13:33 +05:30
```plaintext
2019-03-02 22:35:43 +05:30
GET /projects/:id/registry/repositories/:repository_id/tags/:tag_name
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2019-10-12 21:52:04 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) accessible by the authenticated user. |
2019-03-02 22:35:43 +05:30
| `repository_id` | integer | yes | The ID of registry repository. |
| `tag_name` | string | yes | The name of tag. |
2020-03-13 15:44:24 +05:30
```shell
2019-03-02 22:35:43 +05:30
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-03-13 15:44:24 +05:30
## Delete a registry repository tag
2019-03-02 22:35:43 +05:30
Delete a registry repository tag.
2020-04-08 14:13:33 +05:30
```plaintext
2019-03-02 22:35:43 +05:30
DELETE /projects/:id/registry/repositories/:repository_id/tags/:tag_name
```
| 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. |
| `tag_name` | string | yes | The name of tag. |
2020-03-13 15:44:24 +05:30
```shell
2019-03-02 22:35:43 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0"
```
2021-01-03 14:25:43 +05:30
This action doesn't delete blobs. To delete them and recycle disk space,
2019-09-30 21:07:59 +05:30
[run the garbage collection](https://docs.gitlab.com/omnibus/maintenance/README.html#removing-unused-layers-not-referenced-by-manifests).
2020-03-13 15:44:24 +05:30
## Delete registry repository tags in bulk
2019-03-02 22:35:43 +05:30
2020-03-13 15:44:24 +05:30
Delete registry repository tags in bulk based on given criteria.
2019-03-02 22:35:43 +05:30
2020-05-24 23:13:21 +05:30
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an overview, see [Utilize the Container Registry API to delete all tags except *](https://youtu.be/Hi19bKe_xsg).
2020-04-08 14:13:33 +05:30
```plaintext
2019-03-02 22:35:43 +05:30
DELETE /projects/:id/registry/repositories/:repository_id/tags
```
| 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-06-23 00:09:42 +05:30
| `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`. This field is validated. |
| `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 `.*`. This field is validated. |
2021-01-03 14:25:43 +05:30
| `name_regex_keep` | string | no | The [re2](https://github.com/google/re2/wiki/Syntax) regex of the name to keep. This value overrides any matches from `name_regex_delete`. This field is validated. Note: setting to `.*` results in a no-op. |
2019-03-02 22:35:43 +05:30
| `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:
2021-01-03 14:25:43 +05:30
- It orders all tags by creation date. The creation date is the time of the
manifest creation, not the time of tag push.
- It removes only the tags matching the given `name_regex_delete` (or deprecated
`name_regex`), keeping any that match `name_regex_keep`.
- It never removes the tag named `latest`.
- It keeps N latest matching tags (if `keep_n` is specified).
- It only removes tags that are older than X amount of time (if `older_than` is
specified).
- It schedules the asynchronous job to be executed in the background.
These operations are executed asynchronously and can take time to get executed.
You can run this at most once an hour for a given container repository. This
action doesn't delete blobs. To delete them and recycle disk space,
2019-09-30 21:07:59 +05:30
[run the garbage collection](https://docs.gitlab.com/omnibus/maintenance/README.html#removing-unused-layers-not-referenced-by-manifests).
2019-03-02 22:35:43 +05:30
NOTE: **Note:**
2021-01-03 14:25:43 +05:30
In GitLab 12.4 and later, individual tags are deleted.
2020-06-23 00:09:42 +05:30
For more details, see the [discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/15737).
2019-03-02 22:35:43 +05:30
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-03-13 15:44:24 +05:30
```shell
2020-04-08 14:13:33 +05:30
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-03-02 22:35:43 +05:30
```
2019-10-12 21:52:04 +05:30
1. Remove all tags, but keep always the latest 5:
2019-03-02 22:35:43 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-04-08 14:13:33 +05:30
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-03-02 22:35:43 +05:30
```
2019-10-12 21:52:04 +05:30
1. Remove all tags that are older than 1 month:
2019-03-02 22:35:43 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-04-08 14:13:33 +05:30
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-03-02 22:35:43 +05:30
```