diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/README.md | 1 | ||||
-rw-r--r-- | doc/api/branches.md | 4 | ||||
-rw-r--r-- | doc/api/protected_branches.md | 145 |
3 files changed, 150 insertions, 0 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index 1d2226e2ae8..f63d395b10e 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -43,6 +43,7 @@ following locations: - [Project Access Requests](access_requests.md) - [Project Members](members.md) - [Project Snippets](project_snippets.md) +- [Protected Branches](protected_branches.md) - [Repositories](repositories.md) - [Repository Files](repository_files.md) - [Runners](runners.md) diff --git a/doc/api/branches.md b/doc/api/branches.md index dfaa7d6fab7..80744258acb 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -95,6 +95,8 @@ Example response: ## Protect repository branch +>**Note:** This API endpoint is deprecated in favor of `POST /projects/:id/protected_branches`. + Protects a single project repository branch. This is an idempotent function, protecting an already protected repository branch still returns a `200 OK` status code. @@ -143,6 +145,8 @@ Example response: ## Unprotect repository branch +>**Note:** This API endpoint is deprecated in favor of `DELETE /projects/:id/protected_branches/:name` + Unprotects a single project repository branch. This is an idempotent function, unprotecting an already unprotected repository branch still returns a `200 OK` status code. diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md new file mode 100644 index 00000000000..10faa95d7e8 --- /dev/null +++ b/doc/api/protected_branches.md @@ -0,0 +1,145 @@ +# Protected branches API + +>**Note:** This feature was introduced in GitLab 9.5 + +**Valid access levels** + +The access levels are defined in the `ProtectedBranchAccess::ALLOWED_ACCESS_LEVELS` constant. Currently, these levels are recognized: +``` +0 => No access +30 => Developer access +40 => Master access +``` + +## List protected branches + +Gets a list of protected branches from a project. + +``` +GET /projects/:id/protected_branches +``` + +| 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 | + +```bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_branches' +``` + +Example response: + +```json +[ + { + "name": "master", + "push_access_levels": [ + { + "access_level": 40, + "access_level_description": "Masters" + } + ], + "merge_access_levels": [ + { + "access_level": 40, + "access_level_description": "Masters" + } + ] + }, + ... +] +``` + +## Get a single protected branch or wildcard protected branch + +Gets a single protected branch or wildcard protected branch. + +``` +GET /projects/:id/protected_branches/:name +``` + +| 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 | + +```bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_branches/master' +``` + +Example response: + +```json +{ + "name": "master", + "push_access_levels": [ + { + "access_level": 40, + "access_level_description": "Masters" + } + ], + "merge_access_levels": [ + { + "access_level": 40, + "access_level_description": "Masters" + } + ] +} +``` + +## Protect repository branches + +Protects a single repository branch or several project repository +branches using a wildcard protected branch. + +``` +POST /projects/:id/protected_branches +``` + +```bash +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30' +``` + +| 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`, master access level) | +| `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, master access level) | + +Example response: + +```json +{ + "name": "*-stable", + "push_access_levels": [ + { + "access_level": 30, + "access_level_description": "Developers + Masters" + } + ], + "merge_access_levels": [ + { + "access_level": 30, + "access_level_description": "Developers + Masters" + } + ] +} +``` + +## Unprotect repository branches + +Unprotects the given protected branch or wildcard protected branch. + +``` +DELETE /projects/:id/protected_branches/:name +``` + +```bash +curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_branches/*-stable' +``` + +| 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 | |