受保护分支 API

有效的访问级别#

访问级别在 ProtectedRefAccess.allowed_access_levels 方法中定义。以下级别被认可：

plaintext
0  => No access
30 => Developer access
40 => Maintainer access
60 => Admin access

列出受保护的分支#

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

plaintext
GET /projects/:id/protected_branches

在以下示例中，项目 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  ...
49]

使用极狐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  ...
36]

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

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

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

在以下示例中，项目 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 专业版或旗舰版的用户还会看到 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}

保护仓库分支#

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

plaintext
POST /projects/:id/protected_branches

在以下示例中，项目 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 专业版或旗舰版的用户还会看到 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}

带有部署密钥访问的示例#

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}

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

示例请求：

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            "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}

取消保护仓库分支#

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

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

在以下示例中，项目 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"

更新受保护的分支#

更新受保护的分支。

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

在以下示例中，项目 ID 为 5，分支名称为 feature-branch。

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: 确保更新的用户具有项目访问权限。您还必须在相应的哈希中传递 access_level 的 id。
• group_id: 确保更新的群组共享此项目。您还必须在相应的哈希中传递 access_level 的 id。
• deploy_key_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": []
}

相关主题#

• 受保护的分支
• 分支
• 分支 API