# Protected branches API

> 原文：[https://docs.gitlab.com/ee/api/protected_branches.html](https://docs.gitlab.com/ee/api/protected_branches.html)

*   [List protected branches](#list-protected-branches)
*   [Get a single protected branch or wildcard protected branch](#get-a-single-protected-branch-or-wildcard-protected-branch)
*   [Protect repository branches](#protect-repository-branches)
    *   [Example with user / group level access](#example-with-user--group-level-access-starter)
*   [Unprotect repository branches](#unprotect-repository-branches)
*   [Require code owner approvals for a single branch](#require-code-owner-approvals-for-a-single-branch)

# Protected branches API[](#protected-branches-api "Permalink")

**注意：**此功能是在 GitLab 9.5 中引入的

**有效的访问级别**

访问级别在`ProtectedRefAccess.allowed_access_levels`方法中定义. 当前，这些级别被认可：

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

## List protected branches[](#list-protected-branches "Permalink")

从项目中获取受保护分支的列表.

```
GET /projects/:id/protected_branches 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `search` | string | no | 要搜索的受保护分支的名称或名称的一部分 |

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

响应示例：

```
[  {  "id":  1,  "name":  "master",  "push_access_levels":  [  {  "access_level":  40,  "access_level_description":  "Maintainers"  }  ],  "merge_access_levels":  [  {  "access_level":  40,  "access_level_description":  "Maintainers"  }  ],  "code_owner_approval_required":  "false"  },  ...  ] 
```

使用 GitLab [Starter，Bronze 或更高版本的用户](https://about.gitlab.com/pricing/)还将看到`user_id`和`group_id`参数：

响应示例：

```
[  {  "id":  1,  "name":  "master",  "push_access_levels":  [  {  "access_level":  40,  "user_id":  null,  "group_id":  null,  "access_level_description":  "Maintainers"  }  ],  "merge_access_levels":  [  {  "access_level":  null,  "user_id":  null,  "group_id":  1234,  "access_level_description":  "Example Merge Group"  }  ],  "code_owner_approval_required":  "false"  },  ...  ] 
```

## Get a single protected branch or wildcard protected branch[](#get-a-single-protected-branch-or-wildcard-protected-branch "Permalink")

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

```
GET /projects/:id/protected_branches/:name 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `name` | string | yes | 分支或通配符的名称 |

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

响应示例：

```
{  "id":  1,  "name":  "master",  "push_access_levels":  [  {  "access_level":  40,  "access_level_description":  "Maintainers"  }  ],  "merge_access_levels":  [  {  "access_level":  40,  "access_level_description":  "Maintainers"  }  ],  "code_owner_approval_required":  "false"  } 
```

使用 GitLab [Starter，Bronze 或更高版本的用户](https://about.gitlab.com/pricing/)还将看到`user_id`和`group_id`参数：

响应示例：

```
{  "id":  1,  "name":  "master",  "push_access_levels":  [  {  "access_level":  40,  "user_id":  null,  "group_id":  null,  "access_level_description":  "Maintainers"  }  ],  "merge_access_levels":  [  {  "access_level":  null,  "user_id":  null,  "group_id":  1234,  "access_level_description":  "Example Merge Group"  }  ],  "code_owner_approval_required":  "false"  } 
```

## Protect repository branches[](#protect-repository-branches "Permalink")

使用通配符保护的分支来保护单个存储库分支或几个项目存储库分支.

```
POST /projects/:id/protected_branches 
```

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

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `name` | string | yes | 分支或通配符的名称 |
| `push_access_level` | string | no | 允许推送的访问级别（默认值： `40` ，维护者访问级别） |
| `merge_access_level` | string | no | 允许合并的访问级别（默认值： `40` ，维护者访问级别） |
| `unprotect_access_level` | string | no | 允许取消保护的访问级别（默认值： `40` ，维护者访问级别） |
| `allowed_to_push` | array | no | 允许推送的访问级别数组，每个访问级别由一个哈希表描述 |
| `allowed_to_merge` | array | no | 允许合并的访问级别数组，每个访问级别由哈希描述 |
| `allowed_to_unprotect` | array | no | 允许取消保护的访问级别数组，每个访问级别由一个哈希表描述 |
| `code_owner_approval_required` | boolean | no | 如果它与[`CODEOWNERS`文件](../user/project/code_owners.html)中的项目匹配，则阻止推送到此分支. （默认值：false） |

响应示例：

```
{  "id":  1,  "name":  "*-stable",  "push_access_levels":  [  {  "access_level":  30,  "access_level_description":  "Developers + Maintainers"  }  ],  "merge_access_levels":  [  {  "access_level":  30,  "access_level_description":  "Developers + Maintainers"  }  ],  "unprotect_access_levels":  [  {  "access_level":  40,  "access_level_description":  "Maintainers"  }  ],  "code_owner_approval_required":  "false"  } 
```

使用 GitLab [Starter，Bronze 或更高版本的用户](https://about.gitlab.com/pricing/)还将看到`user_id`和`group_id`参数：

响应示例：

```
{  "id":  1,  "name":  "*-stable",  "push_access_levels":  [  {  "access_level":  30,  "user_id":  null,  "group_id":  null,  "access_level_description":  "Developers + Maintainers"  }  ],  "merge_access_levels":  [  {  "access_level":  30,  "user_id":  null,  "group_id":  null,  "access_level_description":  "Developers + Maintainers"  }  ],  "unprotect_access_levels":  [  {  "access_level":  40,  "user_id":  null,  "group_id":  null,  "access_level_description":  "Maintainers"  }  ],  "code_owner_approval_required":  "false"  } 
```

### Example with user / group level access[](#example-with-user--group-level-access-starter "Permalink")

`allowed_to_push` / `allowed_to_merge` / `allowed_to_unprotect`数组中的元素应采用`{user_id: integer}` ， `{group_id: integer}`或`{access_level: integer}` . 每个用户必须有权访问该项目，并且每个组都必须[共享该项目](../user/project/members/share_project_with_groups.html) . 这些访问级别允许[对受保护的分支访问](../user/project/protected_branches.html#restricting-push-and-merge-access-to-certain-users-starter)进行[更精细的控制，](../user/project/protected_branches.html#restricting-push-and-merge-access-to-certain-users-starter)并在 GitLab 10.3 EE [中将其添加到 API 中](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3516) .

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

响应示例：

```
{  "id":  1,  "name":  "*-stable",  "push_access_levels":  [  {  "access_level":  null,  "user_id":  1,  "group_id":  null,  "access_level_description":  "Administrator"  }  ],  "merge_access_levels":  [  {  "access_level":  40,  "user_id":  null,  "group_id":  null,  "access_level_description":  "Maintainers"  }  ],  "unprotect_access_levels":  [  {  "access_level":  40,  "user_id":  null,  "group_id":  null,  "access_level_description":  "Maintainers"  }  ],  "code_owner_approval_required":  "false"  } 
```

## Unprotect repository branches[](#unprotect-repository-branches "Permalink")

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

```
DELETE /projects/:id/protected_branches/:name 
```

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

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `name` | string | yes | 分支名称 |

## Require code owner approvals for a single branch[](#require-code-owner-approvals-for-a-single-branch "Permalink")

为给定的受保护分支受保护分支更新"需要代码所有者批准"选项.

```
PATCH /projects/:id/protected_branches/:name 
```

```
curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_branches/feature-branch" 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `name` | string | yes | 分支名称 |
| `code_owner_approval_required` | boolean | no | 如果它与[`CODEOWNERS`文件](../user/project/code_owners.html)中的项目匹配，则阻止推送到此分支. （默认值：false） |