group_protected_environments - GitLab

markdown
1---
2stage: Verify
3group: Runner Core
4info: To determine the technical writer assigned to the Stage/Group associated with this page, see <https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments>
5title: 群组级受保护环境 API
6---
7
8<div class="availability">
9
10**Tier**: 专业版，旗舰版
11
12**Offering**: JihuLab.com，私有化部署
13
14</div>
15
16<div class="history">
17
18- 在 GitLab 14.0 中引入。部署在 `group_level_protected_environments` 功能标志后，默认禁用。
19- 功能标志 `group_level_protected_environments` 在 GitLab 14.3 中移除。
20- 在 GitLab 14.3 中 GA。
21
22</div>
23
24使用此 API 与[群组级受保护环境](../ci/environments/protected_environments.md#group-level-protected-environments)进行交互。
25
26> [!注意]
27> 有关受保护环境，请参见[受保护环境 API](protected_environments.md)
28
29## 有效的访问级别 {#valid-access-levels}
30
31访问级别定义在 `ProtectedEnvironments::DeployAccessLevel::ALLOWED_ACCESS_LEVELS` 方法中。
32目前，系统可识别以下级别：
33
34```plaintext
3530 => 开发者访问
3640 => 维护者访问
3760 => 管理员访问

列出所有群组级受保护环境#

列出指定群组的所有受保护环境。

plaintext
GET /groups/:id/protected_environments

属性	类型	必需	描述
id	整数或字符串	是	经认证用户维护的群组的 ID 或 URL 编码路径。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/protected_environments/"

示例响应：

json
1[
2   {
3      "name":"production",
4      "deploy_access_levels":[
5         {
6            "id": 12,
7            "access_level": 40,
8            "access_level_description": "Maintainers",
9            "user_id": null,
10            "group_id": null
11         }
12      ],
13      "required_approval_count": 0
14   }
15]

获取单个受保护环境#

从群组中获取指定的受保护环境。

plaintext
GET /groups/:id/protected_environments/:name

属性	类型	必需	描述
id	整数或字符串	是	经认证用户维护的群组的 ID 或 URL 编码路径。
name	字符串	是	受保护环境的部署层级。可选值：production、staging、testing、development 或 other。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/protected_environments/production"

示例响应：

json
1{
2   "name":"production",
3   "deploy_access_levels":[
4      {
5         "id": 12,
6         "access_level":40,
7         "access_level_description":"Maintainers",
8         "user_id":null,
9         "group_id":null
10      }
11   ],
12   "required_approval_count": 0
13}

保护单个环境#

保护单个环境。

plaintext
POST /groups/:id/protected_environments

属性	类型	必需	描述
id	整数或字符串	是	经认证用户维护的群组的 ID 或 URL 编码路径。
name	字符串	是	受保护环境的部署层级。可选值：production、staging、testing、development 或 other。
deploy_access_levels	数组	是	允许部署的访问级别数组，每个访问级别用一个哈希描述。可选值：user_id、group_id 或 access_level。格式为 {user_id: integer}、{group_id: integer} 或 {access_level: integer}。
approval_rules	数组	否	允许审批的访问级别数组，每个访问级别用一个哈希描述。可选值：user_id、group_id 或 access_level。格式为 {user_id: integer}、{group_id: integer} 或 {access_level: integer}。您还可以通过 required_approvals 字段指定来自指定实体的所需审批数量。参见多审批规则了解更多信息。

可分配的 user_id 是属于给定群组且具有维护者角色（或更高）的用户。可分配的 group_id 是给定群组下的子群组。

shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/22034114/protected_environments" \
  --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}]}'

示例响应：

json
1{
2   "name":"production",
3   "deploy_access_levels":[
4      {
5         "id": 12,
6         "access_level": 40,
7         "access_level_description": "protected-access-group",
8         "user_id": null,
9         "group_id": 9899826
10      }
11   ],
12   "required_approval_count": 0
13}

包含多审批规则的示例：

shell
1curl --request POST \
2  --header "PRIVATE-TOKEN: <your_access_token>" \
3  --header "Content-Type: application/json" \
4  --url "https://gitlab.example.com/api/v4/groups/128/protected_environments" \
5  --data '{
6    "name": "production",
7    "deploy_access_levels": [{"group_id": 138}],
8    "approval_rules": [
9      {"group_id": 134},
10      {"group_id": 135, "required_approvals": 2}
11    ]
12  }'

在此配置中，运维群组 "group_id": 138 只有在 QA 群组 "group_id": 134 和安全群组 "group_id": 135 都批准了部署之后，才能将部署作业执行到 production 环境。

更新受保护环境#

版本历史

在 GitLab 15.4 中引入。

更新单个环境。

plaintext
PUT /groups/:id/protected_environments/:name

属性	类型	必需	描述
id	整数或字符串	是	经认证用户维护的群组的 ID 或 URL 编码路径。
name	字符串	是	受保护环境的部署层级。可选值：production、staging、testing、development 或 other。
deploy_access_levels	数组	否	允许部署的访问级别数组，每个访问级别用一个哈希描述。可选值：user_id、group_id 或 access_level。格式为 {user_id: integer}、{group_id: integer} 或 {access_level: integer}。
required_approval_count	整数	否	部署到此环境所需的审批数量。
approval_rules	数组	否	允许审批的访问级别数组，每个访问级别用一个哈希描述。可选值：user_id、group_id 或 access_level。格式为 {user_id: integer}、{group_id: integer} 或 {access_level: integer}。您还可以通过 required_approvals 字段指定来自指定实体的所需审批数量。参见多审批规则了解更多信息。

要更新：

user_id：确保更新后的用户属于给定群组且具有维护者角色（或更高）。您还必须在相应的哈希中传递 deploy_access_level 或 approval_rule 的 id。
group_id：确保更新后的群组是此受保护环境所属群组的子群组。您还必须在相应的哈希中传递 deploy_access_level 或 approval_rule 的 id。

要删除：

您必须将 _destroy 设置为 true。参见以下示例。

示例：创建 deploy_access_level 记录#

shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/22034114/protected_environments/production" \
  --data '{"deploy_access_levels": [{"group_id": 9899829, "access_level": 40}]}'

示例响应：

json
1{
2   "name": "production",
3   "deploy_access_levels": [
4      {
5         "id": 12,
6         "access_level": 40,
7         "access_level_description": "protected-access-group",
8         "user_id": null,
9         "group_id": 9899829,
10         "group_inheritance_type": 1
11      }
12   ],
13   "required_approval_count": 0
14}

示例：更新 deploy_access_level 记录#

shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/22034114/protected_environments/production" \
  --data '{"deploy_access_levels": [{"id": 12, "group_id": 22034120}]}'

json
1{
2   "name": "production",
3   "deploy_access_levels": [
4      {
5         "id": 12,
6         "access_level": 40,
7         "access_level_description": "protected-access-group",
8         "user_id": null,
9         "group_id": 22034120,
10         "group_inheritance_type": 0
11      }
12   ],
13   "required_approval_count": 2
14}

示例：删除 deploy_access_level 记录#

shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/22034114/protected_environments/production" \
  --data '{"deploy_access_levels": [{"id": 12, "_destroy": true}]}'

示例响应：

json
{
   "name": "production",
   "deploy_access_levels": [],
   "required_approval_count": 0
}

示例：创建 approval_rule 记录#

shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/22034114/protected_environments/production" \
  --data '{"approval_rules": [{"group_id": 134, "required_approvals": 1}]}'

示例响应：

json
1{
2   "name": "production",
3   "approval_rules": [
4      {
5         "id": 38,
6         "user_id": null,
7         "group_id": 134,
8         "access_level": null,
9         "access_level_description": "qa-group",
10         "required_approvals": 1,
11         "group_inheritance_type": 0
12      }
13   ]
14}

示例：更新 approval_rule 记录#

shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/22034114/protected_environments/production" \
  --data '{"approval_rules": [{"id": 38, "group_id": 135, "required_approvals": 2}]}'

json
1{
2   "name": "production",
3   "approval_rules": [
4      {
5         "id": 38,
6         "user_id": null,
7         "group_id": 135,
8         "access_level": null,
9         "access_level_description": "security-group",
10         "required_approvals": 2,
11         "group_inheritance_type": 0
12      }
13   ]
14}

示例：删除 approval_rule 记录#

shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/22034114/protected_environments/production" \
  --data '{"approval_rules": [{"id": 38, "_destroy": true}]}'

示例响应：

json
{
   "name": "production",
   "approval_rules": []
}

取消保护单个环境#

取消保护指定的受保护环境。

plaintext
DELETE /groups/:id/protected_environments/:name

属性	类型	必需	描述
id	整数或字符串	是	经认证用户维护的群组的 ID 或 URL 编码路径。
name	字符串	是	受保护环境的部署层级。可选值：production、staging、testing、development 或 other。

shell
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/protected_environments/staging"

响应应返回 200 状态码。

text
undefined