73c6477b7e
Previously, we used brackets to denote the tier badges, but this made Kramdown, the docs site Markdown renderer, show many warnings when building the site. This is now fixed by using parentheses instead of square brackets. This was caused by [PREMIUM] looking like a link to Kramdown, which couldn't find a URL there. See: - https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/484 - https://gitlab.com/gitlab-org/gitlab-ce/issues/63800
7.8 KiB
7.8 KiB
Protected branches API
Note: This feature was introduced in GitLab 9.5
Valid access levels
The access levels are defined in the ProtectedRefAccess.allowed_access_levels method. Currently, these levels are recognized:
0 => No access
30 => Developer access
40 => Maintainer access
60 => Admin 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 owned by the authenticated user |
curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches'
Example response:
[
{
"name": "master",
"push_access_levels": [
{
"access_level": 40,
"access_level_description": "Maintainers"
}
],
"merge_access_levels": [
{
"access_level": 40,
"access_level_description": "Maintainers"
}
]
},
...
]
Users on GitLab Starter, Bronze, or higher will also see
the user_id and group_id parameters:
Example response:
[
{
"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.
GET /projects/:id/protected_branches/:name
| Attribute | Type | Required | Description |
|---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
name |
string | yes | The name of the branch or wildcard |
curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches/master'
Example response:
{
"name": "master",
"push_access_levels": [
{
"access_level": 40,
"access_level_description": "Maintainers"
}
],
"merge_access_levels": [
{
"access_level": 40,
"access_level_description": "Maintainers"
}
]
}
Users on GitLab Starter, Bronze, or higher will also see
the user_id and group_id parameters:
Example response:
{
"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 branches using a wildcard protected branch.
POST /projects/:id/protected_branches
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 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:
{
"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 will also see
the user_id and group_id parameters:
Example response:
{
"name": "*-stable",
"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. These access levels allow more granular control over protected branch access and were added to the API in in GitLab 10.3 EE.
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:
{
"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"
}
]
}
Unprotect repository branches
Unprotects the given protected branch or wildcard protected branch.
DELETE /projects/:id/protected_branches/:name
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" '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 owned by the authenticated user |
name |
string | yes | The name of the branch |