受保护分支 API

使用此 API 管理 受保护分支。

极狐GitLab 专业版 和 极狐GitLab 旗舰版 支持更细粒度的分支推送保护。管理员可以仅向部署密钥授予修改和推送到受保护分支的权限，而不是特定用户。

有效的访问级别#

ProtectedRefAccess.allowed_access_levels 方法定义了在推送、合并和取消保护配置中使用的以下访问级别。

• 0：无访问权限 - 仅对推送和合并访问级别有效。对取消保护访问级别无效。
• 30：开发者
• 40：维护者
• 60：管理员 - 仅对私有化部署的极狐GitLab 有效。

除了基于角色的访问级别，你还可以通过以下方式分配访问权限：

• 用户 (user_id)：对推送、合并和取消保护访问级别有效。
• 群组 (group_id)：对推送、合并和取消保护访问级别有效。群组在该项目中必须具有 开发者、维护者 或 所有者 角色。
• 部署密钥 (deploy_key_id)：仅对推送访问级别有效。

更多信息，请参阅 保护仓库分支示例。

列出受保护分支#

版本历史

• 部署密钥信息 在 极狐GitLab 16.0 引入。

从项目中获取 受保护分支 的列表，如 UI 中所定义。如果设置了通配符，则返回通配符而不是与该通配符匹配的分支的确切名称。

plaintext
GET /projects/:id/protected_branches

支持的属性：

如果成功，返回 200 OK 和以下响应属性：

在以下示例请求中，项目 ID 为 5。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/protected_branches"

以下示例响应包括：

• 两个受保护分支，ID 分别为 100 和 101。
• push_access_levels，ID 分别为 1001、1002 和 1003。
• merge_access_levels，ID 分别为 2001 和 2002。

json
1[
2  {
3    "id": 100,
4    "name": "main",
5    "push_access_levels": [
6      {
7        "id":  1001,
8        "access_level": 40,
9        "access_level_description": "Maintainers"
10      },
11      {
12        "id": 1002,
13        "access_level": 40,
14        "access_level_description": "Deploy key",
15        "deploy_key_id": 1
16      }
17    ],
18    "merge_access_levels": [
19      {
20        "id":  2001,
21        "access_level": 40,
22        "access_level_description": "Maintainers"
23      }
24    ],
25    "allow_force_push":false,
26    "code_owner_approval_required": false
27  },
28  {
29    "id": 101,
30    "name": "release/*",
31    "push_access_levels": [
32      {
33        "id":  1003,
34        "access_level": 40,
35        "access_level_description": "Maintainers"
36      }
37    ],
38    "merge_access_levels": [
39      {
40        "id":  2002,
41        "access_level": 40,
42        "access_level_description": "Maintainers"
43      }
44    ],
45    "allow_force_push":false,
46    "code_owner_approval_required": false
47  }
48]

极狐GitLab 专业版 或 极狐GitLab 旗舰版 上的用户还可以看到 user_id、group_id 和 inherited 参数。如果存在 inherited 参数，则表示该设置是从项目的群组继承的。

以下示例响应包括：

• 一个受保护分支，ID 为 100。
• push_access_levels，ID 分别为 1001 和 1002。
• merge_access_levels，ID 为 2001。

json
1[
2  {
3    "id": 101,
4    "name": "main",
5    "push_access_levels": [
6      {
7        "id":  1001,
8        "access_level": 40,
9        "user_id": null,
10        "group_id": null,
11        "access_level_description": "Maintainers"
12      },
13      {
14        "id": 1002,
15        "access_level": 40,
16        "access_level_description": "Deploy key",
17        "deploy_key_id": 1,
18        "user_id": null,
19        "group_id": null
20      }
21    ],
22    "merge_access_levels": [
23      {
24        "id":  2001,
25        "access_level": null,
26        "user_id": null,
27        "group_id": 1234,
28        "access_level_description": "Example Merge Group"
29      }
30    ],
31    "allow_force_push":false,
32    "code_owner_approval_required": false,
33    "inherited": true
34  }
35]

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

获取指定的受保护分支或通配符受保护分支。

plaintext
GET /projects/:id/protected_branches/:name

支持的属性：

如果成功，返回 200 OK 和以下响应属性：

在以下示例请求中，项目 ID 为 5，分支名称为 main：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/protected_branches/main"

示例响应：

json
1{
2  "id": 101,
3  "name": "main",
4  "push_access_levels": [
5    {
6      "id":  1001,
7      "access_level": 40,
8      "access_level_description": "Maintainers"
9    }
10  ],
11  "merge_access_levels": [
12    {
13      "id":  2001,
14      "access_level": 40,
15      "access_level_description": "Maintainers"
16    }
17  ],
18  "allow_force_push":false,
19  "code_owner_approval_required": false
20}

极狐GitLab 专业版 或 极狐GitLab 旗舰版 上的用户还可以看到 user_id 和 group_id 参数。

示例响应：

json
1{
2  "id": 101,
3  "name": "main",
4  "push_access_levels": [
5    {
6      "id":  1001,
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":  2001,
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}

保护仓库分支#

版本历史

• deploy_key_id 配置 在 极狐GitLab 17.5 引入。
• deploy_key_id 配置 在 极狐GitLab 18.10 中从 极狐GitLab 专业版 移至 极狐GitLab 基础版。

保护单个仓库分支或使用通配符受保护分支保护多个项目仓库分支。

plaintext
POST /projects/:id/protected_branches

支持的属性：

配置访问级别时：

• 你可以为 allowed_to_push 和 allowed_to_merge 同时设置多个访问级别。
• 最宽松的访问级别决定谁可以执行操作。
• 不要在 allowed_to_push、allowed_to_merge 或 allowed_to_unprotect 数组中包含 id。 id 字段标识现有的访问级别记录，仅在 更新受保护分支 时有效。如果包含的 id 与现有记录不匹配，API 会返回 404 Not Found。

此行为与 UI 不同，UI 在你选择 无人 (access_level: 0) 时会自动清除其他角色选择。

如果成功，返回 201 Created 和以下响应属性：

在以下示例请求中，项目 ID 为 5，分支名称为 *-stable。

shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30&unprotect_access_level=40"

示例响应包括：

• 受保护分支，ID 为 101。
• push_access_levels，ID 为 1001。
• merge_access_levels，ID 为 2001。
• unprotect_access_levels，ID 为 3001。

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

极狐GitLab 专业版 或 极狐GitLab 旗舰版 上的用户还可以看到 user_id 和 group_id 参数：

以下示例响应包括：

• 受保护分支，ID 为 101。
• push_access_levels，ID 为 1001。
• merge_access_levels，ID 为 2001。
• unprotect_access_levels，ID 为 3001。

json
1{
2  "id": 1,
3  "name": "*-stable",
4  "push_access_levels": [
5    {
6      "id":  1001,
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":  2001,
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":  3001,
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} 形式。 每个用户必须有项目的访问权限，每个群组必须 已共享此项目。 这些访问级别可以更精细地控制受保护分支的访问。更多信息，请参阅 配置群组权限。

以下示例请求创建了一个具有用户推送访问权限和群组合并访问权限的受保护分支。 user_id 为 2，group_id 为 3。

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

以下示例响应包括：

• 受保护分支，ID 为 101。
• push_access_levels，ID 为 1001。
• merge_access_levels，ID 为 2001。
• unprotect_access_levels，ID 为 3001。

json
1{
2  "id": 101,
3  "name": "*-stable",
4  "push_access_levels": [
5    {
6      "id":  1001,
7      "access_level": null,
8      "user_id": 2,
9      "group_id": null,
10      "access_level_description": "Administrator"
11    }
12  ],
13  "merge_access_levels": [
14    {
15      "id":  2001,
16      "access_level": null,
17      "user_id": null,
18      "group_id": 3,
19      "access_level_description": "Example Merge Group"
20    }
21  ],
22  "unprotect_access_levels": [
23    {
24      "id":  3001,
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}

部署密钥访问示例#

版本历史

• 在 极狐GitLab 17.5 引入。
• 在 极狐GitLab 18.10 中从 极狐GitLab 专业版 移至 极狐GitLab 基础版。

allowed_to_push 数组中的元素应采用 {user_id: integer}、{group_id: integer}、{deploy_key_id: integer} 或 {access_level: integer} 形式。 该部署密钥必须为你的项目启用，并且必须对你的项目仓库具有写入权限。其他要求，请参阅 允许部署密钥推送到受保护分支。

示例请求：

shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&allowed_to_push[][deploy_key_id]=1"

以下示例响应包括：

• 受保护分支，ID 为 101。
• push_access_levels，ID 为 1001。
• merge_access_levels，ID 为 2001。
• unprotect_access_levels，ID 为 3001。

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

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

版本历史

• 在 13.9 移至 极狐GitLab 专业版。

示例请求：

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": [
7      {"access_level": 30}
8    ],
9    "allowed_to_merge": [
10      {"access_level": 30},
11      {"access_level": 40}
12    ]
13  }' \
14  --url "https://gitlab.example.com/api/v4/projects/5/protected_branches"

以下示例响应包括：

• 受保护分支，ID 为 105。
• push_access_levels，ID 为 1001。
• merge_access_levels，ID 分别为 2001 和 2002。
• unprotect_access_levels，ID 为 3001。

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

json
1{
2    "id": 105,
3    "name": "main",
4    "push_access_levels": [
5        {
6            "id": 1001,
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": 2001,
16            "access_level": 30,
17            "access_level_description": "Developers + Maintainers",
18            "user_id": null,
19            "group_id": null
20        },
21        {
22            "id": 2002,
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": 3001,
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}

使用取消保护访问级别的示例#

要创建一个仅特定群组可以取消保护的分支：

shell
1curl --request POST \
2  --header "PRIVATE-TOKEN: <your_access_token>" \
3  --header "Content-Type: application/json" \
4  --data '{
5    "name": "production",
6    "allowed_to_unprotect": [
7      {"group_id": 789}
8    ]
9  }' \
10  --url "https://gitlab.example.com/api/v4/projects/5/protected_branches"

要允许多种类型的用户取消保护分支：

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_unprotect": [
7      {"user_id": 123},
8      {"group_id": 456},
9      {"access_level": 40}
10    ]
11  }' \
12  --url "https://gitlab.example.com/api/v4/projects/5/protected_branches"

此配置允许以下用户取消保护分支：

• 具有 ID 123 的用户。
• ID 456 群组的成员。
• 具有维护者或所有者角色的用户（访问级别为 40）。

取消保护仓库分支#

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

plaintext
DELETE /projects/:id/protected_branches/:name

支持的属性：

如果成功，返回 204 无内容。

在以下示例请求中，项目 ID 为 5，分支名称为 *-stable：

shell
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/protected_branches/*-stable"

更新受保护分支#

版本历史

• deploy_key_id 配置在极狐GitLab 17.5 中引入。

更新受保护分支。

plaintext
PATCH /projects/:id/protected_branches/:name

支持的属性：

有关设置多个值时的访问级别交互方式的信息，请参见 保护仓库分支。

如果成功，返回 200 OK 和以下响应属性：

示例请求：

shell
curl --request PATCH \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/protected_branches/feature-branch?allow_force_push=true&code_owner_approval_required=true"

allowed_to_push、allowed_to_merge 和 allowed_to_unprotect 数组中的元素应为 user_id、group_id 或 access_level 之一，格式为 {user_id: integer}、{group_id: integer} 或 {access_level: integer}。

allowed_to_push 包含一个额外元素 deploy_key_id，格式为 {deploy_key_id: integer}。

要更新：

• user_id：确保更新的用户有项目的访问权限。在哈希中包含访问级别记录的 id。
• group_id：确保更新的群组 已共享此项目。在哈希中包含访问级别记录的 id。
• deploy_key_id：确保部署密钥已为你的项目启用，并对你的项目仓库具有写入权限。

要更新现有访问级别记录上的任何其他字段，请在哈希中包含该记录的 id。

要删除，必须将 _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/projects/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/projects/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/projects/22034114/protected_branches/main"

示例响应：

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

示例：更新 unprotect_access_level 记录#

先决条件：

• 调用此 API 的用户必须包含在 allowed_to_unprotect 配置中。
• 由 user_id 指定的用户必须是项目成员。
• 由 group_id 指定的群组必须有权访问项目。

要修改谁可以取消保护现有受保护分支，请包含现有访问级别记录的 id。例如：

shell
1curl --request PATCH \
2  --header "PRIVATE-TOKEN: <your_access_token>" \
3  --header "Content-Type: application/json" \
4  --data '{
5    "allowed_to_unprotect": [
6      {"id": 17486, "user_id": 3791}
7    ]
8  }' \
9  --url "https://gitlab.example.com/api/v4/projects/5/protected_branches/main"

要移除特定的访问级别，请使用 _destroy: true。