Use this API to manage Git branches.

To change the branch protections configured for a project, use the protected branches API.

List all repository branches

GET /api/v4/projects/{id}/repository/branches

Lists all repository branches from a specified project, sorted alphabetically by name. Search by name, or use regular expressions to find specific branch patterns. Returns detailed information about the branch, including its protection status, merge status, and commit details.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
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		StringReturn branches containing the search string. Use ^term to find branches that begin with term, and term$ to find branches that end with term
regex
Query		StringReturn branches with names matching an RE2 regular expression. Cannot be used together with search
sort
Query		StringSort results by the specified field and direction
Allowed values: name_asc, updated_asc, updated_desc
page_token
Query		StringName of the branch to start the pagination from. Used for keyset pagination

Responses

CodeDescriptionSchema
200OKArray of APIEntitiesBranch
400Bad Request—
404404 Project Not Found—

Create a repository branch

POST /api/v4/projects/{id}/repository/branches

Creates a branch in the repository.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project

Request body (application/json)

PropertyTypeDescription
branch
Required		StringName of the branch
ref
Required		StringBranch name or commit SHA to create the branch from

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesBranch
400Branch already exists—
404Not Found—

Retrieve a repository branch

GET /api/v4/projects/{id}/repository/branches/{branch}

Retrieves a specified project repository branch.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
branch
Path, required		StringName of the branch

Responses

CodeDescriptionSchema
200OKAPIEntitiesBranch
400Bad Request—
404Project Not Found—

Delete a repository branch

DELETE /api/v4/projects/{id}/repository/branches/{branch}

Deletes a specified branch from the repository.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
branch
Path, required		StringName of the branch

Responses

CodeDescriptionSchema
204No Content—
400Bad Request—
404Branch Not Found—

Check if a branch exists

HEAD /api/v4/projects/{id}/repository/branches/{branch}

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
branch
Path, required		StringName of the branch

Responses

CodeDescriptionSchema
204No Content—
400Bad Request—
404Not Found—

Protect a single branch

PUT /api/v4/projects/{id}/repository/branches/{branch}/protect

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
branch
Path, required		StringName of the branch

Request body (application/json)

PropertyTypeDescription
developers_can_mergeBooleanIf true, allows developers to merge to the branch
developers_can_pushBooleanIf true, allows developers to push to the branch

Responses

CodeDescriptionSchema
200OKAPIEntitiesBranch
400Bad Request—
404404 Branch Not Found—

Unprotect a single branch

PUT /api/v4/projects/{id}/repository/branches/{branch}/unprotect

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
branch
Path, required		StringName of the branch

Responses

CodeDescriptionSchema
200OKAPIEntitiesBranch
400Bad Request—
404404 Branch Not Found—

Delete all merged branches

DELETE /api/v4/projects/{id}/repository/merged_branches

Deletes all branches that are merged into the default branch for a project.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project

Responses

CodeDescriptionSchema
202202 Accepted—
400Bad Request—
404404 Project Not Found—

Schemas

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

APIEntitiesBranch

PropertyTypeDescription
can_pushBooleanExample: true
commitAPIEntitiesCommit—
defaultBooleanExample: true
developers_can_mergeBooleanExample: true
developers_can_pushBooleanExample: true
mergedBooleanExample: true
nameStringExample: master
protectedBooleanExample: true
web_urlStringExample: https://gitlab.example.com/Commit921/the-dude/-/tree/master

APIEntitiesCommit

PropertyTypeDescription
author_emailStringExample: john@example.com
author_nameStringExample: John Smith
authored_dateString (date-time)Example: 2012-05-28T04:42:42-07:00
committed_dateString (date-time)Example: 2012-05-28T04:42:42-07:00
committer_emailStringExample: jack@example.com
committer_nameStringExample: Jack Smith
created_atString (date-time)Example: 2017-07-26T11:08:53.000+02:00
extended_trailersObjectExample: {"Signed-off-by":["John Doe \u003cjohndoe@gitlab.com\u003e","Jane Doe \u003cjanedoe@gitlab.com\u003e"]}
idStringExample: 2695effb5807a22ff3d138d593fd856244e155e7
messageStringExample: Initial commit
parent_idsArray of stringsExample: ["2a4b78934375d7f53875269ffd4f45fd83a84ebe"]
short_idStringExample: 2695effb
titleStringExample: Initial commit
trailersObjectExample: {"Merged-By":"Jane Doe janedoe@gitlab.com"}
web_urlStringExample: https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746
←
REST API / Boards
REST API / Broadcast messages
→