Branches API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Use the branches API to manage a project’s Git branches programmatically.

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

List repository branches

Get a list of repository branches from a project, sorted by name alphabetically. 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.

This endpoint can be accessed without authentication if the repository is publicly accessible.

GET /projects/:id/repository/branches

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`regex`	string	No	Return list of branches with names matching a re2 regular expression. Cannot be used together with `search`.
`search`	string	No	Return list of branches containing the search string. You can use `^term` to find branches that begin with `term`, and `term$` to find branches that end with `term`.

If successful, returns 200 OK and the following response attributes:

Attribute	Type	Description
`can_push`	boolean	If `true`, the authenticated user can push to this branch.
`commit`	object	Details about the most recent commit on the branch.
`commit.author_email`	string	Email address of the user who authored the change.
`commit.author_name`	string	Name of the user who authored the change.
`commit.authored_date`	datetime (ISO 8601)	When the commit was authored.
`commit.committed_date`	datetime (ISO 8601)	When the commit was committed.
`commit.committer_email`	string	Email address of the user who committed the change.
`commit.committer_name`	string	Name of the user who committed the change.
`commit.created_at`	datetime (ISO 8601)	When the commit was created.
`commit.extended_trailers`	object	Extended Git trailers parsed from the commit message.
`commit.id`	string	Full SHA of the commit.
`commit.message`	string	Full commit message.
`commit.parent_ids`	array	Array of parent commit SHAs.
`commit.short_id`	string	Abbreviated SHA of the commit.
`commit.title`	string	Title of the commit message.
`commit.trailers`	object	Git trailers parsed from the commit message.
`commit.web_url`	string	URL to view the commit in the GitLab UI.
`default`	boolean	If `true`, the branch is the default branch for the project.
`developers_can_merge`	boolean	If `true`, users with at least the Developer role can merge to this branch.
`developers_can_push`	boolean	If `true`, users with at least the Developer role can push to this branch.
`merged`	boolean	If `true`, the branch has been merged into the default branch.
`name`	string	Name of the branch.
`protected`	boolean	If `true`, the branch is protected from force pushes and deletion.
`web_url`	string	URL to view the branch in the GitLab UI.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/branches"

Example response:

[
  {
    "name": "main",
    "merged": false,
    "protected": true,
    "default": true,
    "developers_can_push": false,
    "developers_can_merge": false,
    "can_push": true,
    "web_url": "https://gitlab.example.com/my-group/my-project/-/tree/main",
    "commit": {
      "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
      "short_id": "7b5c3cc",
      "created_at": "2024-06-28T03:44:20-07:00",
      "parent_ids": [
        "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
      ],
      "title": "add projects API",
      "message": "add projects API",
      "author_name": "John Smith",
      "author_email": "john@example.com",
      "authored_date": "2024-06-27T05:51:39-07:00",
      "committer_name": "John Smith",
      "committer_email": "john@example.com",
      "committed_date": "2024-06-28T03:44:20-07:00",
      "trailers": {},
      "extended_trailers": {},
      "web_url": "https://gitlab.example.com/my-group/my-project/-/commit/7b5c3cc8be40ee161ae89a06bba6229da1032a0c"
    }
  },
  ...
]

Get single repository branch

Get a single project repository branch.

This endpoint can be accessed without authentication if the repository is publicly accessible.

GET /projects/:id/repository/branches/:branch

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`branch`	string	Yes	URL-encoded name of the branch.

If successful, returns 200 OK and the following response attributes:

Attribute	Type	Description
`can_push`	boolean	Whether the authenticated user can push to this branch.
`commit`	object	Details about the latest commit on the branch.
`commit.author_email`	string	Email address of the commit author.
`commit.author_name`	string	Name of the commit author.
`commit.authored_date`	string	Date and time when the commit was authored, in ISO 8601 format.
`commit.committer_email`	string	Email address of the user who committed the change.
`commit.committer_name`	string	Name of the user who committed the change.
`commit.committed_date`	string	Date and time when the commit was committed, in ISO 8601 format.
`commit.created_at`	string	Date and time when the commit was created, in ISO 8601 format.
`commit.extended_trailers`	object	Extended Git trailers parsed from the commit message.
`commit.id`	string	Full SHA of the commit.
`commit.message`	string	Full commit message.
`commit.parent_ids`	array	Array of parent commit SHAs.
`commit.short_id`	string	Abbreviated SHA of the commit.
`commit.title`	string	Title of the commit message.
`commit.trailers`	object	Git trailers parsed from the commit message.
`commit.web_url`	string	URL to view the commit in the GitLab UI.
`default`	boolean	Whether this is the default branch for the project.
`developers_can_merge`	boolean	Whether users with the Developer role can merge to this branch.
`developers_can_push`	boolean	Whether users with the Developer role can push to this branch.
`merged`	boolean	Whether the branch has been merged into the default branch.
`name`	string	Name of the branch.
`protected`	boolean	Whether the branch is protected from force pushes and deletion.
`web_url`	string	URL to view the branch in the GitLab UI.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/branches/main"

Example response:

{
  "name": "main",
  "merged": false,
  "protected": true,
  "default": true,
  "developers_can_push": false,
  "developers_can_merge": false,
  "can_push": true,
  "web_url": "https://gitlab.example.com/my-group/my-project/-/tree/main",
  "commit": {
    "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
    "short_id": "7b5c3cc",
    "created_at": "2012-06-28T03:44:20-07:00",
    "parent_ids": [
      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
    ],
    "title": "add projects API",
    "message": "add projects API",
    "author_name": "John Smith",
    "author_email": "john@example.com",
    "authored_date": "2012-06-27T05:51:39-07:00",
    "committer_name": "John Smith",
    "committer_email": "john@example.com",
    "committed_date": "2012-06-28T03:44:20-07:00",
    "trailers": {},
    "extended_trailers": {},
    "web_url": "https://gitlab.example.com/my-group/my-project/-/commit/7b5c3cc8be40ee161ae89a06bba6229da1032a0c"
  }
}

Protect repository branch

See POST /projects/:id/protected_branches for information on protecting repository branches.

Unprotect repository branch

See DELETE /projects/:id/protected_branches/:name for information on unprotecting repository branches.

Create repository branch

Create a new branch in the repository.

POST /projects/:id/repository/branches

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`branch`	string	Yes	Name of the branch. Cannot contain spaces or special characters except hyphens and underscores.
`ref`	string	Yes	Branch name or commit SHA to create the branch from.

If successful, returns 201 Created and the following response attributes:

Attribute	Type	Description
`can_push`	boolean	If `true`, the authenticated user can push to this branch.
`commit`	object	Details about the latest commit on the branch.
`commit.author_email`	string	Email address of the commit author.
`commit.author_name`	string	Name of the commit author.
`commit.authored_date`	string	Date and time when the commit was authored, in ISO 8601 format.
`commit.committed_date`	string	Date and time when the commit was committed, in ISO 8601 format.
`commit.committer_email`	string	Email address of the user who committed the change.
`commit.committer_name`	string	Name of the user who committed the change.
`commit.created_at`	string	Date and time when the commit was created, in ISO 8601 format.
`commit.extended_trailers`	object	Extended Git trailers parsed from the commit message.
`commit.id`	string	Full SHA of the commit.
`commit.message`	string	Full commit message.
`commit.parent_ids`	array	Array of parent commit SHAs.
`commit.short_id`	string	Abbreviated SHA of the commit.
`commit.title`	string	Title of the commit message.
`commit.trailers`	object	Git trailers parsed from the commit message.
`commit.web_url`	string	URL to view the commit in the GitLab UI.
`default`	boolean	If `true`, sets this branch is the default branch for the project.
`developers_can_merge`	boolean	If `true`, users with the Developer role can merge to this branch.
`developers_can_push`	boolean	If `true`, users with the Developer role can push to this branch.
`merged`	boolean	If `true`, the branch merged into the default branch.
`name`	string	Name of the branch.
`protected`	boolean	If `true`, the branch is protected from force pushes and deletion.
`web_url`	string	URL to view the branch in the GitLab UI.

Example request:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/branches?branch=newbranch&ref=main"

Example response:

{
  "commit": {
    "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
    "short_id": "7b5c3cc",
    "created_at": "2012-06-28T03:44:20-07:00",
    "parent_ids": [
      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
    ],
    "title": "add projects API",
    "message": "add projects API",
    "author_name": "John Smith",
    "author_email": "john@example.com",
    "authored_date": "2012-06-27T05:51:39-07:00",
    "committer_name": "John Smith",
    "committer_email": "john@example.com",
    "committed_date": "2012-06-28T03:44:20-07:00",
    "trailers": {},
    "extended_trailers": {},
    "web_url": "https://gitlab.example.com/my-group/my-project/-/commit/7b5c3cc8be40ee161ae89a06bba6229da1032a0c"
  },
  "name": "newbranch",
  "merged": false,
  "protected": false,
  "default": false,
  "developers_can_push": false,
  "developers_can_merge": false,
  "can_push": true,
  "web_url": "https://gitlab.example.com/my-group/my-project/-/tree/newbranch"
}

Delete repository branch

Delete a branch from the repository.

In the case of an error, an explanation message is provided.

DELETE /projects/:id/repository/branches/:branch

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`branch`	string	Yes	URL-encoded name of the branch. Cannot delete the default branch or protected branches.

If successful, returns 204 No Content.

Example request:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/branches/newbranch"

Deleting a branch does not completely erase all related data. Some information persists to maintain project history and to support recovery processes. For more information, see Handle sensitive information.

Delete merged branches

Deletes all branches that are merged into the project’s default branch.

Protected branches are not deleted as part of this operation.

DELETE /projects/:id/repository/merged_branches

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.

If successful, returns 202 Accepted.

Example request:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/merged_branches"

Branches API

List repository branches

Get single repository branch

Protect repository branch

Unprotect repository branch

Create repository branch

Delete repository branch

Delete merged branches

Related topics