diff options
Diffstat (limited to 'doc/api/protected_branches.md')
| -rw-r--r-- | doc/api/protected_branches.md | 124 |
1 files changed, 117 insertions, 7 deletions
diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index 620cb0e0bae..96bd5c15f13 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -43,12 +43,14 @@ Example response: "name": "master", "push_access_levels": [ { + "id": 1, "access_level": 40, "access_level_description": "Maintainers" } ], "merge_access_levels": [ { + "id": 1, "access_level": 40, "access_level_description": "Maintainers" } @@ -61,12 +63,14 @@ Example response: "name": "release/*", "push_access_levels": [ { + "id": 1, "access_level": 40, "access_level_description": "Maintainers" } ], "merge_access_levels": [ { + "id": 1, "access_level": 40, "access_level_description": "Maintainers" } @@ -90,6 +94,7 @@ Example response: "name": "master", "push_access_levels": [ { + "id": 1, "access_level": 40, "user_id": null, "group_id": null, @@ -98,6 +103,7 @@ Example response: ], "merge_access_levels": [ { + "id": 1, "access_level": null, "user_id": null, "group_id": 1234, @@ -136,12 +142,14 @@ Example response: "name": "master", "push_access_levels": [ { + "id": 1, "access_level": 40, "access_level_description": "Maintainers" } ], "merge_access_levels": [ { + "id": 1, "access_level": 40, "access_level_description": "Maintainers" } @@ -162,6 +170,7 @@ Example response: "name": "master", "push_access_levels": [ { + "id": 1, "access_level": 40, "user_id": null, "group_id": null, @@ -170,6 +179,7 @@ Example response: ], "merge_access_levels": [ { + "id": 1, "access_level": null, "user_id": null, "group_id": 1234, @@ -215,18 +225,21 @@ Example response: "name": "*-stable", "push_access_levels": [ { + "id": 1, "access_level": 30, "access_level_description": "Developers + Maintainers" } ], "merge_access_levels": [ { + "id": 1, "access_level": 30, "access_level_description": "Developers + Maintainers" } ], "unprotect_access_levels": [ { + "id": 1, "access_level": 40, "access_level_description": "Maintainers" } @@ -247,6 +260,7 @@ Example response: "name": "*-stable", "push_access_levels": [ { + "id": 1, "access_level": 30, "user_id": null, "group_id": null, @@ -255,6 +269,7 @@ Example response: ], "merge_access_levels": [ { + "id": 1, "access_level": 30, "user_id": null, "group_id": null, @@ -263,6 +278,7 @@ Example response: ], "unprotect_access_levels": [ { + "id": 1, "access_level": 40, "user_id": null, "group_id": null, @@ -291,6 +307,7 @@ Example response: "name": "*-stable", "push_access_levels": [ { + "id": 1, "access_level": null, "user_id": 1, "group_id": null, @@ -299,6 +316,7 @@ Example response: ], "merge_access_levels": [ { + "id": 1, "access_level": 40, "user_id": null, "group_id": null, @@ -307,6 +325,7 @@ Example response: ], "unprotect_access_levels": [ { + "id": 1, "access_level": 40, "user_id": null, "group_id": null, @@ -348,6 +367,7 @@ Example response: "name": "master", "push_access_levels": [ { + "id": 1, "access_level": 30, "access_level_description": "Developers + Maintainers", "user_id": null, @@ -356,12 +376,14 @@ Example response: ], "merge_access_levels": [ { + "id": 1, "access_level": 30, "access_level_description": "Developers + Maintainers", "user_id": null, "group_id": null }, { + "id": 2, "access_level": 40, "access_level_description": "Maintainers", "user_id": null, @@ -370,6 +392,7 @@ Example response: ], "unprotect_access_levels": [ { + "id": 1, "access_level": 40, "access_level_description": "Maintainers", "user_id": null, @@ -398,20 +421,107 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch | -## Require code owner approvals for a single branch **(PREMIUM)** +## Update a protected branch -Update the "code owner approval required" option for the given protected branch. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101903) in GitLab 15.6. + +Updates a protected branch. ```plaintext PATCH /projects/:id/protected_branches/:name ``` ```shell -curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_branches/feature-branch?code_owner_approval_required=true" +curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_branches/feature-branch?allow_force_push=true&code_owner_approval_required=true" ``` -| Attribute | Type | Required | Description | +| Attribute | Type | Required | Description | | -------------------------------------------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `name` | string | yes | The name of the branch | -| `code_owner_approval_required` | boolean | no | Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/code_owners.md). (defaults: false)| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `name` | string | yes | The name of the branch | +| `allow_force_push` | boolean | no | When enabled, members who can push to this branch can also force push. | +| `code_owner_approval_required` **(PREMIUM)** | boolean | no | Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/code_owners.md). Defaults to `false`. | +| `allowed_to_push` **(PREMIUM)** | array | no | Array of push access levels, with each described by a hash. | +| `allowed_to_merge` **(PREMIUM)** | array | no | Array of merge access levels, with each described by a hash. | +| `allowed_to_unprotect` **(PREMIUM)** | array | no | Array of unprotect access levels, with each described by a hash. | + +Elements in the `allowed_to_push`, `allowed_to_merge` and `allowed_to_unprotect` arrays should be one of `user_id`, `group_id` or +`access_level`, and take the form `{user_id: integer}`, `{group_id: integer}` or +`{access_level: integer}`. + +To update: + +- `user_id`: Ensure the updated user has access to the project. You must also pass the + `id` of the `access_level` in the respective hash. +- `group_id`: Ensure the updated group [has this project shared](../user/project/members/share_project_with_groups.md). + You must also pass the `id` of the `access_level` in the respective hash. + +To delete: + +- You must pass `_destroy` set to `true`. See the following examples. + +### Example: create a `push_access_level` record + +```shell +curl --header 'Content-Type: application/json' --request PATCH \ + --data '{"push_access_levels": [{"group_id": 9899829, access_level: 40}]}' \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/22034114/protected_branches/master" +``` + +Example response: + +```json +{ + "name": "master", + "allowed_to_push": [ + { + "id": 12, + "access_level": 40, + "access_level_description": "Administrator", + "user_id": null, + "group_id": 9899829 + } + ] +} +``` + +### Example: update a `push_access_level` record + +```shell +curl --header 'Content-Type: application/json' --request PUT \ + --data '{"push_access_levels": [{"id": 12, "group_id": 22034120}]' \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/22034114/protected_branches/master" +``` + +```json +{ + "name": "master", + "deploy_access_levels": [ + { + "id": 12, + "access_level": 40, + "access_level_description": "Administrator", + "user_id": null, + "group_id": 22034120 + } + ] +} +``` + +### Example: delete a `push_access_level` record + +```shell +curl --header 'Content-Type: application/json' --request PUT \ + --data '{"push_access_levels": [{"id": 12, "_destroy": true}]' \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/22034114/protected_branches/master" +``` + +Example response: + +```json +{ + "name": "master", + "push_access_levels": [] +} +``` |