diff options
Diffstat (limited to 'doc/api/protected_branches.md')
| -rw-r--r-- | doc/api/protected_branches.md | 77 |
1 files changed, 72 insertions, 5 deletions
diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index a261bb75be5..44980c7c649 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -10,6 +10,7 @@ The access levels are defined in the `ProtectedRefAccess.allowed_access_levels` 0 => No access 30 => Developer access 40 => Maintainer access +60 => Admin access ``` ## List protected branches @@ -37,13 +38,17 @@ Example response: "push_access_levels": [ { "access_level": 40, + "user_id": null, + "group_id": null, "access_level_description": "Maintainers" } ], "merge_access_levels": [ { - "access_level": 40, - "access_level_description": "Maintainers" + "access_level": null, + "user_id": null, + "group_id": 1234, + "access_level_description": "Example Merge Group" } ] }, @@ -76,13 +81,17 @@ Example response: "push_access_levels": [ { "access_level": 40, + "user_id": null, + "group_id": null, "access_level_description": "Maintainers" } ], "merge_access_levels": [ { - "access_level": 40, - "access_level_description": "Maintainers" + "access_level": null, + "user_id": null, + "group_id": 1234, + "access_level_description": "Example Merge Group" } ] } @@ -98,7 +107,7 @@ POST /projects/:id/protected_branches ``` ```bash -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' +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 | @@ -107,6 +116,11 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitla | `name` | string | yes | The name of the branch or wildcard | | `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, maintainer access level) | | `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, maintainer access level) | +| `unprotect_access_level` | string | no | Access levels allowed to unprotect (defaults: `40`, maintainer access level) | +| `allowed_to_push` | array | no | Array of access levels allowed to push, with each described by a hash | +| `allowed_to_merge` | array | no | Array of access levels allowed to merge, with each described by a hash | +| `allowed_to_unprotect` | array | no | Array of access levels allowed to unprotect, with each described by a hash | + Example response: @@ -116,13 +130,64 @@ Example response: "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" + } + ] +} +``` + +### Example with user / group level access + +Elements in the `allowed_to_push` / `allowed_to_merge` / `allowed_to_unprotect` array should take the +form `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/share_project_with_groups.md). These access levels allow [more granular control over protected branch access](../user/project/protected_branches.md#restricting-push-and-merge-access-to-certain-users-starter) and were [added to the API in ][ee-3516] in GitLab 10.3 EE. + +```bash +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' +``` + +Example response: + +```json +{ + "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" } ] } @@ -144,3 +209,5 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" 'https://git | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch | + +[ee-3516]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3516 "ProtectedBranches API handles per user/group granularity" |