群组级别的受保护分支 API

  • Tier: 专业版, 旗舰版
  • Offering: 私有化部署
History
    • 引入于极狐GitLab 15.9,使用名为 group_protected_branches功能标志。默认禁用。
    • 在极狐GitLab 15.11 中,功能标志 group_protected_branches 重命名为 allow_protected_branches_for_group
    • 在极狐GitLab 17.6 中 GA。功能标志 group_protected_branches 被移除。

使用群组的受保护分支 API 来管理受保护分支规则。它提供了列出、创建、更新和删除适用于群组所属项目的受保护分支规则的端点。

群组的受保护分支设置仅限于顶级群组。

有效访问级别#

访问级别在 ProtectedRefAccess.allowed_access_levels 方法中定义。这些级别包括:

plaintext
0 => 无访问 30 => 开发者访问 40 => 维护者访问 60 => 管理员访问

列出受保护分支#

从群组中获取受保护分支的列表。如果设置了通配符,则返回匹配该通配符的分支的确切名称。

plaintext
GET /groups/:id/protected_branches
属性类型必需描述
id整数或字符串群组的 ID 或 URL 编码路径
search字符串要搜索的受保护分支的名称或部分名称。
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/groups/5/protected_branches"

示例响应:

json
1[ 2 { 3 "id": 1, 4 "name": "main", 5 "push_access_levels": [ 6 { 7 "id": 1, 8 "access_level": 40, 9 "user_id": null, 10 "group_id": 1234, 11 "access_level_description": "Maintainers" 12 } 13 ], 14 "merge_access_levels": [ 15 { 16 "id": 1, 17 "access_level": 40, 18 "user_id": null, 19 "group_id": 1234, 20 "access_level_description": "Maintainers" 21 } 22 ], 23 "allow_force_push":false, 24 "code_owner_approval_required": false 25 }, 26 { 27 "id": 1, 28 "name": "release/*", 29 "push_access_levels": [ 30 { 31 "id": 1, 32 "access_level": 40, 33 "user_id": null, 34 "group_id": null, 35 "access_level_description": "Maintainers" 36 } 37 ], 38 "merge_access_levels": [ 39 { 40 "id": 1, 41 "access_level": 40, 42 "user_id": null, 43 "group_id": 1234, 44 "access_level_description": "Maintainers" 45 } 46 ], 47 "allow_force_push":false, 48 "code_owner_approval_required": false 49 }, 50 ... 51]

获取单个受保护分支或通配符受保护分支#

获取单个受保护分支或通配符受保护分支。

plaintext
GET /groups/:id/protected_branches/:name
属性类型必需描述
id整数或字符串群组的 ID 或 URL 编码路径
name字符串分支或通配符的名称。
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/groups/5/protected_branches/main"

示例响应:

json
1{ 2 "id": 1, 3 "name": "main", 4 "push_access_levels": [ 5 { 6 "id": 1, 7 "access_level": 40, 8 "user_id": null, 9 "group_id": null, 10 "access_level_description": "Maintainers" 11 } 12 ], 13 "merge_access_levels": [ 14 { 15 "id": 1, 16 "access_level": null, 17 "user_id": null, 18 "group_id": 1234, 19 "access_level_description": "Example Merge Group" 20 } 21 ], 22 "allow_force_push":false, 23 "code_owner_approval_required": false 24}

保护仓库分支#

使用通配符受保护分支保护单个仓库分支。

plaintext
POST /groups/:id/protected_branches
shell
curl --request POST \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/groups/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30&unprotect_access_level=40"
属性类型必需描述
id整数或字符串群组的 ID 或 URL 编码路径
name字符串分支或通配符的名称。
allow_force_push布尔值允许具有推送访问权限的所有用户进行强制推送。默认值:false
allowed_to_merge数组允许合并的访问级别数组,每个由 {user_id: integer}{group_id: integer}{access_level: integer} 形式的哈希描述。
allowed_to_push数组允许推送的访问级别数组,每个由 {user_id: integer}{group_id: integer}{access_level: integer} 形式的哈希描述。
allowed_to_unprotect数组允许取消保护的访问级别数组,每个由 {user_id: integer}{group_id: integer}{access_level: integer} 形式的哈希描述。
code_owner_approval_required布尔值如果该分支匹配 CODEOWNERS 文件 中的项目,则阻止推送。默认值:false
merge_access_level整数允许合并的访问级别。默认值:40,维护者角色。
push_access_level整数允许推送的访问级别。默认值:40,维护者角色。
unprotect_access_level整数允许取消保护的访问级别。默认值:40,维护者角色。

示例响应:

json
1{ 2 "id": 1, 3 "name": "*-stable", 4 "push_access_levels": [ 5 { 6 "id": 1, 7 "access_level": 30, 8 "user_id": null, 9 "group_id": null, 10 "access_level_description": "Developers + Maintainers" 11 } 12 ], 13 "merge_access_levels": [ 14 { 15 "id": 1, 16 "access_level": 30, 17 "user_id": null, 18 "group_id": null, 19 "access_level_description": "Developers + Maintainers" 20 } 21 ], 22 "unprotect_access_levels": [ 23 { 24 "id": 1, 25 "access_level": 40, 26 "user_id": null, 27 "group_id": null, 28 "access_level_description": "Maintainers" 29 } 30 ], 31 "allow_force_push":false, 32 "code_owner_approval_required": false 33}

用户和群组访问示例#

allowed_to_push / allowed_to_merge / allowed_to_unprotect 数组中的元素应该采用 {user_id: integer}{group_id: integer}{access_level: integer} 的形式。每个用户必须有权访问项目,每个群组必须共享此项目。这些访问级别允许更细粒度地控制受保护分支的访问

shell
curl --request POST \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/groups/5/protected_branches?name=*-stable&allowed_to_push%5B%5D%5Buser_id%5D=1"

示例响应:

json
1{ 2 "id": 1, 3 "name": "*-stable", 4 "push_access_levels": [ 5 { 6 "id": 1, 7 "access_level": null, 8 "user_id": 1, 9 "group_id": null, 10 "access_level_description": "Administrator" 11 } 12 ], 13 "merge_access_levels": [ 14 { 15 "id": 1, 16 "access_level": 40, 17 "user_id": null, 18 "group_id": null, 19 "access_level_description": "Maintainers" 20 } 21 ], 22 "unprotect_access_levels": [ 23 { 24 "id": 1, 25 "access_level": 40, 26 "user_id": null, 27 "group_id": null, 28 "access_level_description": "Maintainers" 29 } 30 ], 31 "allow_force_push":false, 32 "code_owner_approval_required": false 33}

允许推送和允许合并访问示例#

示例请求:

shell
1curl --request POST \ 2 --header "PRIVATE-TOKEN: <your_access_token>" \ 3 --header "Content-Type: application/json" \ 4 --data '{ 5 "name": "main", 6 "allowed_to_push": [{"access_level": 30}], 7 "allowed_to_merge": [{ 8 "access_level": 30 9 },{ 10 "access_level": 40 11 } 12 ]}' 13 --url "https://gitlab.example.com/api/v4/groups/5/protected_branches"

示例响应:

json
1{ 2 "id": 5, 3 "name": "main", 4 "push_access_levels": [ 5 { 6 "id": 1, 7 "access_level": 30, 8 "access_level_description": "Developers + Maintainers", 9 "user_id": null, 10 "group_id": null 11 } 12 ], 13 "merge_access_levels": [ 14 { 15 "id": 1, 16 "access_level": 30, 17 "access_level_description": "Developers + Maintainers", 18 "user_id": null, 19 "group_id": null 20 }, 21 { 22 "id": 2, 23 "access_level": 40, 24 "access_level_description": "Maintainers", 25 "user_id": null, 26 "group_id": null 27 } 28 ], 29 "unprotect_access_levels": [ 30 { 31 "id": 1, 32 "access_level": 40, 33 "access_level_description": "Maintainers", 34 "user_id": null, 35 "group_id": null 36 } 37 ], 38 "allow_force_push":false, 39 "code_owner_approval_required": false 40}

取消保护仓库分支#

取消保护给定的受保护分支或通配符受保护分支。

plaintext
DELETE /groups/:id/protected_branches/:name
shell
curl --request DELETE \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/groups/5/protected_branches/*-stable"
属性类型必需描述
id整数或字符串群组的 ID 或 URL 编码路径
name字符串分支的名称。

示例响应:

json
1{ 2 "name": "main", 3 "push_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}

更新受保护分支#

更新受保护分支。

plaintext
PATCH /groups/:id/protected_branches/:name
shell
curl --request PATCH \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/groups/5/protected_branches/feature-branch?allow_force_push=true&code_owner_approval_required=true"
属性类型必需描述
id整数或字符串群组的 ID 或 URL 编码路径
name字符串分支的名称。
allow_force_push布尔值启用后,能够推送到此分支的成员也可以进行强制推送。
allowed_to_push数组推送访问级别数组,每个由哈希描述。
allowed_to_merge数组合并访问级别数组,每个由哈希描述。
allowed_to_unprotect数组取消保护访问级别数组,每个由哈希描述。
code_owner_approval_required布尔值如果该分支匹配 CODEOWNERS 文件 中的项目,则阻止推送。默认值:false

allowed_to_pushallowed_to_mergeallowed_to_unprotect 数组中的元素应该:

  • user_idgroup_idaccess_level 之一。
  • 采用 {user_id: integer}{group_id: integer}{access_level: integer} 的形式。

要更新:

  • user_id: 确保更新的用户有权访问项目。还必须传递各自哈希中的 access_levelid
  • group_id: 确保更新的群组共享此项目。 还必须传递各自哈希中的 access_levelid

要删除:

  • 必须传递 _destroy 设置为 true。参见以下示例。

示例:创建 push_access_level 记录#

shell
curl --header 'Content-Type: application/json' --request PATCH \ --data '{"allowed_to_push": [{access_level: 40}]}' \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/groups/22034114/protected_branches/main"

示例响应:

json
1{ 2 "name": "main", 3 "push_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}

示例:更新 push_access_level 记录#

shell
curl --header 'Content-Type: application/json' --request PATCH \ --data '{"allowed_to_push": [{"id": 12, "access_level": 0}]' \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/groups/22034114/protected_branches/main"

示例响应:

json
1{ 2 "name": "main", 3 "push_access_levels": [ 4 { 5 "id": 12, 6 "access_level": 0, 7 "access_level_description": "No One", 8 "user_id": null, 9 "group_id": null 10 } 11 ] 12}

示例:删除 push_access_level 记录#

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

示例响应:

json
{ "name": "main", "push_access_levels": [] }