diff options
Diffstat (limited to 'doc/api/protected_branches.md')
| -rw-r--r-- | doc/api/protected_branches.md | 72 |
1 files changed, 47 insertions, 25 deletions
diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index 5f6e03fde4d..d3091cb1e15 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -19,6 +19,8 @@ The access levels are defined in the `ProtectedRefAccess.allowed_access_levels` ## List protected branches +> Deploy key information [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116846) in GitLab 16.0. + Gets a list of protected branches from a project as they are defined [in the UI](../user/project/protected_branches.md#configure-a-protected-branch). If a wildcard is set, it is returned instead of the exact name of the branches that match that wildcard. ```plaintext @@ -46,6 +48,12 @@ Example response: "id": 1, "access_level": 40, "access_level_description": "Maintainers" + }, + { + "id": 2, + "access_level": 40, + "access_level_description": "Deploy key", + "deploy_key_id": 1 } ], "merge_access_levels": [ @@ -82,7 +90,7 @@ Example response: ] ``` -Users on GitLab Premium or higher also see +Users on GitLab Premium or Ultimate also see the `user_id`, `group_id` and `inherited` parameters. If the `inherited` parameter exists, means the setting was inherited from the project's group. @@ -100,6 +108,14 @@ Example response: "user_id": null, "group_id": null, "access_level_description": "Maintainers" + }, + { + "id": 2, + "access_level": 40, + "access_level_description": "Deploy key", + "deploy_key_id": 1, + "user_id": null, + "group_id": null } ], "merge_access_levels": [ @@ -161,7 +177,7 @@ Example response: } ``` -Users on GitLab Premium or higher also see +Users on GitLab Premium or Ultimate also see the `user_id` and `group_id` parameters: Example response: @@ -208,16 +224,16 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla | Attribute | Type | Required | Description | | -------------------------------------------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `name` | string | yes | The name of the branch or wildcard | -| `push_access_level` | integer | no | Access levels allowed to push (defaults: `40`, Maintainer role) | -| `merge_access_level` | integer | no | Access levels allowed to merge (defaults: `40`, Maintainer role) | -| `unprotect_access_level` | integer | no | Access levels allowed to unprotect (defaults: `40`, Maintainer role) | -| `allow_force_push` | boolean | no | Allow all users with push access to force push. (default: `false`) | -| `allowed_to_push` **(PREMIUM)** | array | no | Array of access levels allowed to push, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}` | -| `allowed_to_merge` **(PREMIUM)** | array | no | Array of access levels allowed to merge, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}` | -| `allowed_to_unprotect` **(PREMIUM)** | array | no | Array of access levels allowed to unprotect, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}` | -| `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: false) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. +| `name` | string | yes | The name of the branch or wildcard. +| `allow_force_push` | boolean | no | Allow all users with push access to force push. (default: `false`) +| `allowed_to_merge` **(PREMIUM)** | array | no | Array of access levels allowed to merge, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}`. +| `allowed_to_push` **(PREMIUM)** | array | no | Array of access levels allowed to push, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}`. +| `allowed_to_unprotect` **(PREMIUM)** | array | no | Array of access levels allowed to unprotect, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}`. The access level `No access` is not available for this field. | +| `code_owner_approval_required` **(PREMIUM)** | boolean | no | Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/codeowners/index.md). (defaults: false) +| `merge_access_level` | integer | no | Access levels allowed to merge. (defaults: `40`, Maintainer role) +| `push_access_level` | integer | no | Access levels allowed to push. (defaults: `40`, Maintainer role) +| `unprotect_access_level` | integer | no | Access levels allowed to unprotect. (defaults: `40`, Maintainer role) Example response: @@ -251,7 +267,7 @@ Example response: } ``` -Users on GitLab Premium or higher also see +Users on GitLab Premium or Ultimate also see the `user_id` and `group_id` parameters: Example response: @@ -369,7 +385,7 @@ Example response: "name": "master", "push_access_levels": [ { - "id": 1, + "id": 1, "access_level": 30, "access_level_description": "Developers + Maintainers", "user_id": null, @@ -378,14 +394,14 @@ Example response: ], "merge_access_levels": [ { - "id": 1, + "id": 1, "access_level": 30, "access_level_description": "Developers + Maintainers", "user_id": null, "group_id": null }, { - "id": 2, + "id": 2, "access_level": 40, "access_level_description": "Maintainers", "user_id": null, @@ -394,7 +410,7 @@ Example response: ], "unprotect_access_levels": [ { - "id": 1, + "id": 1, "access_level": 40, "access_level_description": "Maintainers", "user_id": null, @@ -437,15 +453,15 @@ 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?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](rest/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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/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. +| `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. The access level `No access` is not available for this field. +| `code_owner_approval_required` **(PREMIUM)** | boolean | no | Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/codeowners/index.md). Defaults to `false`. | 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 @@ -529,3 +545,9 @@ Example response: "push_access_levels": [] } ``` + +## Related topics + +- [Protected branches](../user/project/protected_branches.md) +- [Branches](../user/project/repository/branches/index.md) +- [Branches API](branches.md) |