Use this API to manage protected branches for a project, and the protected branch settings that all projects in a group inherit.

GitLab Premium and GitLab Ultimate support more granular protections for pushing to branches. Administrators can grant permission to modify and push to protected branches only to deploy keys, instead of specific users.

Group protected branch settings are restricted to top-level groups. They support only valid access levels, and cannot name individual users or groups.

List all protected branches

GET /api/v4/projects/{id}/protected_branches

Lists all protected branches for a specified project.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
Example: gitlab-org/gitlab
page
Query		IntegerPage number of results to retrieve
Default: 1
Example: 1
per_page
Query		IntegerNumber of items to list per page
Default: 20
Example: 20
search
Query		StringName or part of the name of protected branches to search for
Example: mai

Responses

CodeDescriptionSchema
200OKArray of APIEntitiesProtectedBranch
400Bad Request—
401401 Unauthorized—
404404 Project Not Found—

Protect repository branches

POST /api/v4/projects/{id}/protected_branches

Protects a specified repository branch or several project repository branches using a wildcard protected branch.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
Example: gitlab-org/gitlab

Request body (application/json)

PropertyTypeDescription
allow_force_pushBooleanIf true, members who can push to this branch can also force push
Default: false
allowed_to_mergeArray of objectsArray of merge access levels, with each described by a hash of the form {user_id: integer}, {group_id: integer}, or {access_level: integer}
allowed_to_pushArray of objectsArray of push access levels, with each described by a hash of the form {user_id: integer}, {group_id: integer}, {deploy_key_id: integer}, or {access_level: integer}
merge_access_levelIntegerAccess level allowed to merge. Defaults to 40 (Maintainer role)
Allowed values: 30, 40, 60, 0
name
Required		StringName of the branch or wildcard
Example: main
push_access_levelIntegerAccess level allowed to push. Defaults to 40 (Maintainer role)
Allowed values: 30, 40, 60, 0

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesProtectedBranch
400Bad Request—
401401 Unauthorized—
404404 Project Not Found—
409Protected branch ‘main’ already exists—
422name is missing—

Retrieve a protected branch or wildcard protected branch

GET /api/v4/projects/{id}/protected_branches/{name}

Retrieves a specified protected branch or wildcard protected branch.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
Example: gitlab-org/gitlab
name
Path, required		StringName of the branch or wildcard
Example: main

Responses

CodeDescriptionSchema
200OKAPIEntitiesProtectedBranch
400Bad Request—
401401 Unauthorized—
404404 Project Not Found—

Update a protected branch

PATCH /api/v4/projects/{id}/protected_branches/{name}

Updates a protected branch for a specified project.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
Example: gitlab-org/gitlab
name
Path, required		StringName of the branch or wildcard
Example: main

Request body (application/json)

PropertyTypeDescription
allow_force_pushBooleanIf true, members who can push to this branch can also force push
allowed_to_mergeArray of objectsArray of merge access levels, with each described by a hash of the form {user_id: integer}, {group_id: integer}, or {access_level: integer}
allowed_to_pushArray of objectsArray of push access levels, with each described by a hash of the form {user_id: integer}, {group_id: integer}, {deploy_key_id: integer}, or {access_level: integer}

Responses

CodeDescriptionSchema
200OKAPIEntitiesProtectedBranch
400400 Bad request—
401401 Unauthorized—
404404 Project Not Found—
422Push access levels access level has already been taken—

Unprotect repository branches

DELETE /api/v4/projects/{id}/protected_branches/{name}

Unprotects a specified protected branch or wildcard protected branch.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
Example: gitlab-org/gitlab
name
Path, required		StringName of the branch or wildcard
Example: main

Responses

CodeDescriptionSchema
204No Content—
400Bad Request—
401401 Unauthorized—
404404 Project Not Found—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesProtectedBranch

PropertyTypeDescription
allow_force_pushBoolean—
idInteger (int64)Example: 1
merge_access_levelsArray of APIEntitiesProtectedRefAccess—
nameStringExample: main
push_access_levelsArray of APIEntitiesProtectedRefAccess—

APIEntitiesProtectedRefAccess

PropertyTypeDescription
access_levelIntegerExample: 40
access_level_descriptionStringExample: Maintainers
deploy_key_idInteger (int64)Example: 1
group_idIntegerExample: 1
idInteger (int64)Example: 1
user_idIntegerExample: 1
←
REST API / Projects job token scope
REST API / Protected environments
→