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

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.

GET /projects/:id/repository/branches

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
search	string	no	Return list of branches matching the search criteria.

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

Example response:

[
  {
    "name": "master",
    "merged": false,
    "protected": true,
    "default": true,
    "developers_can_push": false,
    "developers_can_merge": false,
    "can_push": true,
    "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. This endpoint can be accessed without authentication if the repository is publicly accessible.

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

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

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

Example response:

{
  "name": "master",
  "merged": false,
  "protected": true,
  "default": true,
  "developers_can_push": false,
  "developers_can_merge": false,
  "can_push": true,
  "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

Note: This API endpoint is deprecated in favor of POST /projects/:id/protected_branches.

Protects a single project repository branch. This is an idempotent function, protecting an already protected repository branch still returns a 200 OK status code.

PUT /projects/:id/repository/branches/:branch/protect

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches/master/protect?developers_can_push=true&developers_can_merge=true

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
branch	string	yes	The name of the branch
developers_can_push	boolean	no	Flag if developers can push to the branch
developers_can_merge	boolean	no	Flag if developers can merge to the branch

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": "master",
  "merged": false,
  "protected": true,
  "default": true,
  "developers_can_push": true,
  "developers_can_merge": true,
  "can_push": true
}

Unprotect repository branch

Note: This API endpoint is deprecated in favor of DELETE /projects/:id/protected_branches/:name

Unprotects a single project repository branch. This is an idempotent function, unprotecting an already unprotected repository branch still returns a 200 OK status code.

PUT /projects/:id/repository/branches/:branch/unprotect

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

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

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": "master",
  "merged": false,
  "protected": false,
  "default": true,
  "developers_can_push": false,
  "developers_can_merge": false,
  "can_push": true
}

Create repository branch

POST /projects/:id/repository/branches

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

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

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
}

Delete repository branch

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

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

In case of an error, an explaining message is provided.

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

Delete merged branches

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

Protected branches will not be deleted as part of this operation.

DELETE /projects/:id/repository/merged_branches

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

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