Protected branches API · Gitlab 中文文檔

# 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） |