gitlab-org--gitlab-foss/doc/api/branches.md

stage	group	info	type
Create	Source Code	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments	reference, api

Branches API (FREE)

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.

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

GET /projects/:id/repository/branches

Parameters:

Attribute	Type	Required	Description
id	integer/string	yes	ID or URL-encoded path of the project owned by the authenticated user.
search	string	no	Return list of branches containing the search string. You can use ^term and term$ to find branches that begin and end with term respectively.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "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": {
      "author_email": "john@example.com",
      "author_name": "John Smith",
      "authored_date": "2012-06-27T05:51:39-07:00",
      "committed_date": "2012-06-28T03:44:20-07:00",
      "committer_email": "john@example.com",
      "committer_name": "John Smith",
      "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
      "short_id": "7b5c3cc",
      "title": "add projects API",
      "message": "add projects API",
      "parent_ids": [
        "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
      ]
    }
  },
  ...
]

Get single repository branch

Get a single project repository branch.

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

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

Parameters:

Attribute	Type	Required	Description
id	integer/string	yes	ID or URL-encoded path of the project owned by the authenticated user.
branch	string	yes	Name of the branch.

Example request:

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

Example response:

{
  "name": "master",
  "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": {
    "author_email": "john@example.com",
    "author_name": "John Smith",
    "authored_date": "2012-06-27T05:51:39-07:00",
    "committed_date": "2012-06-28T03:44:20-07:00",
    "committer_email": "john@example.com",
    "committer_name": "John Smith",
    "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
    "short_id": "7b5c3cc",
    "title": "add projects API",
    "message": "add projects API",
    "parent_ids": [
      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
    ]
  }
}

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

Parameters:

Attribute	Type	Required	Description
id	integer	yes	ID or URL-encoded path of the project owned by the authenticated user.
branch	string	yes	Name of the branch.
ref	string	yes	Branch name or commit SHA to create branch from.

Example request:

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

Example response:

{
  "commit": {
    "author_email": "john@example.com",
    "author_name": "John Smith",
    "authored_date": "2012-06-27T05:51:39-07:00",
    "committed_date": "2012-06-28T03:44:20-07:00",
    "committer_email": "john@example.com",
    "committer_name": "John Smith",
    "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
    "short_id": "7b5c3cc",
    "title": "add projects API",
    "message": "add projects API",
    "parent_ids": [
      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
    ]
  },
  "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.

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

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

Parameters:

Attribute	Type	Required	Description
id	integer/string	yes	ID or URL-encoded path of the project owned by the authenticated user.
branch	string	yes	Name of the branch.

Example request:

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

Delete merged branches

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

NOTE: Protected branches are not deleted as part of this operation.

DELETE /projects/:id/repository/merged_branches

Parameters:

Attribute	Type	Required	Description
id	integer/string	yes	ID or URL-encoded path of the project owned by the authenticated user.

Example request:

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