Branches API

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

This API operates on repository branches.

See also Protected branches API.

List repository branches

Get a list of repository branches from a project, sorted by name alphabetically.

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

Copy to clipboard
GET /projects/:id/repository/branches

Parameters:

AttributeTypeRequiredDescription
idinteger or stringyesID or URL-encoded path of the project.
searchstringnoReturn list of branches containing the search string. Use ^term to find branches that begin with term, and term$ to find branches that end with term.
regexstringnoReturn list of branches with names matching a re2 regular expression.

Example request:

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

Example response:

Copy to clipboard
[
  {
    "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.

Copy to clipboard
GET /projects/:id/repository/branches/:branch

Parameters:

AttributeTypeRequiredDescription
idinteger or stringyesID or URL-encoded path of the project.
branchstringyesURL-encoded name of the branch.

Example request:

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

Example response:

Copy to clipboard
{
  "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": {},
    "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.

Copy to clipboard
POST /projects/:id/repository/branches

Parameters:

AttributeTypeRequiredDescription
idintegeryesID or URL-encoded path of the project.
branchstringyesName of the branch.
refstringyesBranch name or commit SHA to create branch from.

Example request:

Copy to clipboard
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:

Copy to clipboard
{
  "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": {},
    "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.

Copy to clipboard
DELETE /projects/:id/repository/branches/:branch

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesID or URL-encoded path of the project.
branchstringyesName of the branch.

Example request:

Copy to clipboard
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.

Copy to clipboard
DELETE /projects/:id/repository/merged_branches

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesID or URL-encoded path of the project.

Example request:

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