diff options
Diffstat (limited to 'doc/api/group_protected_environments.md')
| -rw-r--r-- | doc/api/group_protected_environments.md | 177 |
1 files changed, 174 insertions, 3 deletions
diff --git a/doc/api/group_protected_environments.md b/doc/api/group_protected_environments.md index 0f1527f8968..3f1d932e0c8 100644 --- a/doc/api/group_protected_environments.md +++ b/doc/api/group_protected_environments.md @@ -15,7 +15,7 @@ Read more about [group-level protected environments](../ci/environments/protecte ## Valid access levels -The access levels are defined in the `ProtectedEnvironment::DeployAccessLevel::ALLOWED_ACCESS_LEVELS` method. +The access levels are defined in the `ProtectedEnvironments::DeployAccessLevel::ALLOWED_ACCESS_LEVELS` method. Currently, these levels are recognized: ```plaintext @@ -48,13 +48,14 @@ Example response: "name":"production", "deploy_access_levels":[ { + "id": 12, "access_level": 40, "access_level_description": "Maintainers", "user_id": null, "group_id": null } ], - "required_approval_count": 0 + "required_approval_count": 0 } ] ``` @@ -83,6 +84,7 @@ Example response: "name":"production", "deploy_access_levels":[ { + "id": 12, "access_level":40, "access_level_description":"Maintainers", "user_id":null, @@ -123,13 +125,182 @@ Example response: "name":"production", "deploy_access_levels":[ { + "id": 12, "access_level": 40, "access_level_description": "protected-access-group", "user_id": null, "group_id": 9899826 } ], - "required_approval_count": 0 + "required_approval_count": 0 +} +``` + +## Update an environment + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351854) in GitLab 15.4. + +Updates a single environment. + +```plaintext +PUT /groups/:id/protected_environments/:name +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `name` | string | yes | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).| +| `deploy_access_levels` | array | no | Array of access levels allowed to deploy, with each described by a hash. One of `user_id`, `group_id` or `access_level`. They take the form of `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}` respectively. | +| `required_approval_count` | integer | no | The number of approvals required to deploy to this environment. | +| `approval_rules` | array | no | Array of access levels allowed to approve, with each described by a hash. One of `user_id`, `group_id` or `access_level`. They take the form of `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}` respectively. You can also specify the number of required approvals from the specified entity with `required_approvals` field. See [Multiple approval rules](../ci/environments/deployment_approvals.md#multiple-approval-rules) for more information. | + +To update: + +- **`user_id`**: Ensure the updated user belongs to the given group with the Maintainer role (or above). You must also pass the `id` of either a `deploy_access_level` or `approval_rule` in the respective hash. +- **`group_id`**: Ensure the updated group is a sub-group of the group this protected environment belongs to. You must also pass the `id` of either a `deploy_access_level` or `approval_rule` in the respective hash. + +To delete: + +- You must pass `_destroy` set to `true`. See the following examples. + +### Example: Create a `deploy_access_level` record + +```shell +curl --header 'Content-Type: application/json' --request PUT \ + --data '{"deploy_access_levels": [{"group_id": 9899829, access_level: 40}], "required_approval_count": 1}' \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/groups/22034114/protected_environments/production" +``` + +Example response: + +```json +{ + "name": "production", + "deploy_access_levels": [ + { + "id": 12, + "access_level": 40, + "access_level_description": "protected-access-group", + "user_id": null, + "group_id": 9899829, + "group_inheritance_type": 1 + } + ], + "required_approval_count": 0 +} +``` + +### Example: Update a `deploy_access_level` record + +```shell +curl --header 'Content-Type: application/json' --request PUT \ + --data '{"deploy_access_levels": [{"id": 12, "group_id": 22034120}], "required_approval_count": 2}' \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22034114/protected_environments/production" +``` + +```json +{ + "name": "production", + "deploy_access_levels": [ + { + "id": 12, + "access_level": 40, + "access_level_description": "protected-access-group", + "user_id": null, + "group_id": 22034120, + "group_inheritance_type": 0 + } + ], + "required_approval_count": 2 +} +``` + +### Example: Delete a `deploy_access_level` record + +```shell +curl --header 'Content-Type: application/json' --request PUT \ + --data '{"deploy_access_levels": [{"id": 12, "_destroy": true}], "required_approval_count": 0}' \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22034114/protected_environments/production" +``` + +Example response: + +```json +{ + "name": "production", + "deploy_access_levels": [], + "required_approval_count": 0 +} +``` + +### Example: Create an `approval_rule` record + +```shell +curl --header 'Content-Type: application/json' --request PUT \ + --data '{"approval_rules": [{"group_id": 134, "required_approvals": 1}]}' \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/groups/22034114/protected_environments/production" +``` + +Example response: + +```json +{ + "name": "production", + "approval_rules": [ + { + "id": 38, + "user_id": null, + "group_id": 134, + "access_level": null, + "access_level_description": "qa-group", + "required_approvals": 1, + "group_inheritance_type": 0 + } + ] +} +``` + +### Example: Update an `approval_rule` record + +```shell +curl --header 'Content-Type: application/json' --request PUT \ + --data '{"approval_rules": [{"id": 38, "group_id": 135, "required_approvals": 2}]}' \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22034114/protected_environments/production" +``` + +```json +{ + "name": "production", + "approval_rules": [ + { + "id": 38, + "user_id": null, + "group_id": 135, + "access_level": null, + "access_level_description": "security-group", + "required_approvals": 2, + "group_inheritance_type": 0 + } + ] +} +``` + +### Example: Delete an `approval_rule` record + +```shell +curl --header 'Content-Type: application/json' --request PUT \ + --data '{"approval_rules": [{"id": 38, "_destroy": true}]}' \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22034114/protected_environments/production" +``` + +Example response: + +```json +{ + "name": "production", + "approval_rules": [] } ``` |