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 integerThe ID or URL-encoded path of the project
Example: gitlab-org/gitlab
page
Query		IntegerCurrent page number
Default: 1
Example: 1
per_page
Query		IntegerNumber of items per page
Default: 20
Example: 20
search
Query		StringSearch for a protected branch by name
Example: mai

Responses

CodeDescriptionSchema
200OKAPIEntitiesProtectedBranch
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 integerThe ID or URL-encoded path of the project
Example: gitlab-org/gitlab

Request body (application/json)

PropertyTypeDescription
allow_force_pushBooleanAllow force push for all users with push access
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 levels allowed to merge (defaults: 40, maintainer access level)
Allowed values: 30, 40, 60, 0
name
Required		StringThe name of the protected branch
Example: main
push_access_levelIntegerAccess levels allowed to push (defaults: 40, maintainer access level)
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 integerThe ID or URL-encoded path of the project
Example: gitlab-org/gitlab
name
Path, required		StringThe name 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 integerThe ID or URL-encoded path of the project
Example: gitlab-org/gitlab
name
Path, required		StringThe name of the branch
Example: main

Request body (application/json)

PropertyTypeDescription
allow_force_pushBooleanAllow force push for all users with push access
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 integerThe ID or URL-encoded path of the project
Example: gitlab-org/gitlab
name
Path, required		StringThe name of the protected branch
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
→