diff options
author | Greg Myers <gmyers@gitlab.com> | 2019-08-27 15:51:04 +0000 |
---|---|---|
committer | Greg Myers <gmyers@gitlab.com> | 2019-08-27 15:51:04 +0000 |
commit | 51a0166af2c532aa7a0d04bb503b43499be97033 (patch) | |
tree | 9ebd74e8518d573fe4860763ddb41146dab1f453 /doc/api/protected_branches.md | |
parent | f706677357fcdf9cd870d098379788543ea71058 (diff) | |
parent | 27c222d16ccb666878c7ac558f484efa56f77f37 (diff) | |
download | gitlab-ce-51a0166af2c532aa7a0d04bb503b43499be97033.tar.gz |
Merge branch 'master' into 'api-curl-quote-url-docs'api-curl-quote-url-docs
# Conflicts:
# doc/api/events.md
Diffstat (limited to 'doc/api/protected_branches.md')
-rw-r--r-- | doc/api/protected_branches.md | 154 |
1 files changed, 149 insertions, 5 deletions
diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index a261bb75be5..ffb4a70168b 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 @@ -51,6 +52,36 @@ Example response: ] ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `user_id` and `group_id` parameters: + +Example response: + +```json +[ + { + "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" + } + ] + }, + ... +] +``` + ## Get a single protected branch or wildcard protected branch Gets a single protected branch or wildcard protected branch. @@ -88,6 +119,33 @@ Example response: } ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `user_id` and `group_id` parameters: + +Example response: + +```json +{ + "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" + } + ] +} +``` + ## Protect repository branches Protects a single repository branch or several project repository @@ -98,15 +156,48 @@ 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 | | --------- | ---- | -------- | ----------- | -| `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 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) | +| `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 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 | **(STARTER)** Array of access levels allowed to push, with each described by a hash | +| `allowed_to_merge` | array | no | **(STARTER)** Array of access levels allowed to merge, with each described by a hash | +| `allowed_to_unprotect` | array | no | **(STARTER)**Array of access levels allowed to unprotect, with each described by a hash | + +Example response: + +```json +{ + "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" + } + ] +} +``` + +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `user_id` and `group_id` parameters: Example response: @@ -116,14 +207,67 @@ 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 **(STARTER)** + +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](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/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" + } ] } ``` |