diff options
Diffstat (limited to 'doc/api/protected_tags.md')
| -rw-r--r-- | doc/api/protected_tags.md | 72 |
1 files changed, 49 insertions, 23 deletions
diff --git a/doc/api/protected_tags.md b/doc/api/protected_tags.md index 633ca441fad..7aff87b54f0 100644 --- a/doc/api/protected_tags.md +++ b/doc/api/protected_tags.md @@ -8,17 +8,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w **Valid access levels** -Currently, these levels are recognized: +These access levels are recognized: -```plaintext -0 => No access -30 => Developer access -40 => Maintainer access -``` +- `0`: No access +- `30`: Developer role +- `40`: Maintainer role ## List protected tags -Gets a list of protected tags from a project. +> Deploy key information [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116846) in GitLab 16.0. + +Gets a list of [protected tags](../user/project/protected_tags.md) from a project. This function takes pagination parameters `page` and `per_page` to restrict the list of protected tags. ```plaintext @@ -27,10 +27,11 @@ GET /projects/:id/protected_tags | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_tags" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/5/protected_tags" ``` Example response: @@ -44,6 +45,12 @@ Example response: "id":1, "access_level": 40, "access_level_description": "Maintainers" + }, + { + "id": 2, + "access_level": 40, + "access_level_description": "Deploy key", + "deploy_key_id": 1 } ] }, @@ -54,7 +61,6 @@ Example response: ## Get a single protected tag or wildcard protected tag Gets a single protected tag or wildcard protected tag. -The pagination parameters `page` and `per_page` can be used to restrict the list of protected tags. ```plaintext GET /projects/:id/protected_tags/:name @@ -62,11 +68,12 @@ GET /projects/:id/protected_tags/:name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `name` | string | yes | The name of the tag or wildcard | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `name` | string | yes | The name of the tag or wildcard. | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_tags/release-1-0" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/5/protected_tags/release-1-0" ``` Example response: @@ -86,23 +93,35 @@ Example response: ## Protect repository tags -Protects a single repository tag or several project repository -tags using a wildcard protected tag. +Protects a single repository tag, or several project repository +tags, using a wildcard protected tag. ```plaintext POST /projects/:id/protected_tags ``` ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_tags?name=*-stable&create_access_level=30" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/5/protected_tags" -d '{ + "allowed_to_create" : [ + { + "user_id" : 1 + }, + { + "access_level" : 30 + } + ], + "create_access_level" : 30, + "name" : "*-stable" +}' ``` | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `name` | string | yes | The name of the tag or wildcard | -| `create_access_level` | string | no | Access levels allowed to create (defaults: `40`, Maintainer role) | -| `allowed_to_create` | array | no | Array of access levels allowed to create tags, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}` | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `name` | string | yes | The name of the tag or wildcard. | +| `allowed_to_create` | array | no | Array of access levels allowed to create tags, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}`. | +| `create_access_level` | string | no | Access levels allowed to create. Default: `40`, for Maintainer role. | Example response: @@ -128,10 +147,17 @@ DELETE /projects/:id/protected_tags/:name ``` ```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_tags/*-stable" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/5/protected_tags/*-stable" ``` | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `name` | string | yes | The name of the tag | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `name` | string | yes | The name of the tag. | + +## Related topics + +- [Tags API](tags.md) for all tags +- [Tags](../user/project/repository/tags/index.md) user documentation +- [Protected tags](../user/project/protected_tags.md) user documentation |