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 integerThe ID or URL-encoded path of the project
page
Query		IntegerCurrent page number
Default: 1
Example: 1
per_page
Query		IntegerNumber of items per page
Default: 20
Example: 20
search
Query		StringReturn list of branches matching the search criteria
regex
Query		StringReturn list of branches matching the regex
sort
Query		StringReturn list of branches sorted by the given field
Allowed values: name_asc, updated_asc, updated_desc
page_token
Query		StringName of branch to start the pagination from

Responses

CodeDescriptionSchema
200OKAPIEntitiesBranch
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 integerThe ID or URL-encoded path of the project

Request body (application/json)

PropertyTypeDescription
branch
Required		StringThe name of the branch
ref
Required		StringCreate branch from commit sha or existing branch

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 integerThe ID or URL-encoded path of the project
branch
Path, required		StringThe name 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 integerThe ID or URL-encoded path of the project
branch
Path, required		StringThe name 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 integerThe ID or URL-encoded path of the project
branch
Path, required		StringThe name 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 integerThe ID or URL-encoded path of the project
branch
Path, required		StringThe name of the branch

Request body (application/json)

PropertyTypeDescription
developers_can_mergeBooleanFlag if developers can merge to that branch
developers_can_pushBooleanFlag if developers can push to that 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 integerThe ID or URL-encoded path of the project
branch
Path, required		StringThe name 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 integerThe ID 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
→