2017-05-18 04:49:03 -04:00
|
|
|
# Branches API
|
2014-03-31 09:43:45 -04:00
|
|
|
|
|
|
|
## List repository branches
|
|
|
|
|
|
|
|
Get a list of repository branches from a project, sorted by name alphabetically.
|
2017-03-20 04:37:14 -04:00
|
|
|
This endpoint can be accessed without authentication if the repository is
|
|
|
|
publicly accessible.
|
2014-03-31 09:43:45 -04:00
|
|
|
|
|
|
|
```
|
|
|
|
GET /projects/:id/repository/branches
|
|
|
|
```
|
|
|
|
|
2016-01-18 02:21:01 -05:00
|
|
|
| Attribute | Type | Required | Description |
|
|
|
|
| --------- | ---- | -------- | ----------- |
|
2017-04-08 04:54:00 -04:00
|
|
|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
|
2014-03-31 09:43:45 -04:00
|
|
|
|
2016-01-18 02:21:01 -05:00
|
|
|
```bash
|
2017-03-01 12:39:40 -05:00
|
|
|
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/repository/branches
|
2016-01-18 02:21:01 -05:00
|
|
|
```
|
|
|
|
|
|
|
|
Example response:
|
2014-03-31 09:43:45 -04:00
|
|
|
|
|
|
|
```json
|
|
|
|
[
|
|
|
|
{
|
2016-01-18 02:21:01 -05:00
|
|
|
"name": "master",
|
2016-11-28 13:16:15 -05:00
|
|
|
"merged": false,
|
2016-01-18 02:21:01 -05:00
|
|
|
"protected": true,
|
2016-07-12 10:31:55 -04:00
|
|
|
"developers_can_push": false,
|
2016-07-19 04:36:18 -04:00
|
|
|
"developers_can_merge": false,
|
2014-03-31 09:43:45 -04:00
|
|
|
"commit": {
|
2015-02-15 09:01:27 -05:00
|
|
|
"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",
|
2014-03-31 09:43:45 -04:00
|
|
|
"id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
|
2016-10-27 09:26:58 -04:00
|
|
|
"short_id": "7b5c3cc",
|
|
|
|
"title": "add projects API",
|
2014-03-31 09:43:45 -04:00
|
|
|
"message": "add projects API",
|
2015-02-15 09:01:27 -05:00
|
|
|
"parent_ids": [
|
|
|
|
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
|
|
|
|
]
|
2016-01-18 02:21:01 -05:00
|
|
|
}
|
|
|
|
},
|
|
|
|
...
|
2014-03-31 09:43:45 -04:00
|
|
|
]
|
|
|
|
```
|
|
|
|
|
|
|
|
## Get single repository branch
|
|
|
|
|
2017-03-20 04:37:14 -04:00
|
|
|
Get a single project repository branch. This endpoint can be accessed without
|
|
|
|
authentication if the repository is publicly accessible.
|
2014-03-31 09:43:45 -04:00
|
|
|
|
|
|
|
```
|
|
|
|
GET /projects/:id/repository/branches/:branch
|
|
|
|
```
|
|
|
|
|
2016-01-18 02:21:01 -05:00
|
|
|
| Attribute | Type | Required | Description |
|
|
|
|
| --------- | ---- | -------- | ----------- |
|
2017-04-08 04:54:00 -04:00
|
|
|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
|
2016-01-18 02:21:01 -05:00
|
|
|
| `branch` | string | yes | The name of the branch |
|
2014-03-31 09:43:45 -04:00
|
|
|
|
2016-01-18 02:21:01 -05:00
|
|
|
```bash
|
2017-03-01 12:39:40 -05:00
|
|
|
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/repository/branches/master
|
2016-01-18 02:21:01 -05:00
|
|
|
```
|
|
|
|
|
|
|
|
Example response:
|
2014-03-31 09:43:45 -04:00
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
2016-01-18 02:21:01 -05:00
|
|
|
"name": "master",
|
2016-11-28 13:16:15 -05:00
|
|
|
"merged": false,
|
2016-01-18 02:21:01 -05:00
|
|
|
"protected": true,
|
2016-07-12 10:31:55 -04:00
|
|
|
"developers_can_push": false,
|
2016-07-19 04:36:18 -04:00
|
|
|
"developers_can_merge": false,
|
2014-03-31 09:43:45 -04:00
|
|
|
"commit": {
|
2015-02-15 09:01:27 -05:00
|
|
|
"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",
|
2014-03-31 09:43:45 -04:00
|
|
|
"id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
|
2016-10-27 09:26:58 -04:00
|
|
|
"short_id": "7b5c3cc",
|
|
|
|
"title": "add projects API",
|
2014-03-31 09:43:45 -04:00
|
|
|
"message": "add projects API",
|
2015-02-15 09:01:27 -05:00
|
|
|
"parent_ids": [
|
|
|
|
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
|
|
|
|
]
|
2016-01-18 02:21:01 -05:00
|
|
|
}
|
2014-03-31 09:43:45 -04:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
## Protect repository branch
|
|
|
|
|
2016-01-18 02:21:01 -05:00
|
|
|
Protects a single project repository branch. This is an idempotent function,
|
|
|
|
protecting an already protected repository branch still returns a `200 OK`
|
|
|
|
status code.
|
2014-03-31 09:43:45 -04:00
|
|
|
|
|
|
|
```
|
|
|
|
PUT /projects/:id/repository/branches/:branch/protect
|
|
|
|
```
|
|
|
|
|
2016-01-18 02:21:01 -05:00
|
|
|
```bash
|
2017-03-01 12:39:40 -05:00
|
|
|
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/repository/branches/master/protect?developers_can_push=true&developers_can_merge=true
|
2016-01-18 02:21:01 -05:00
|
|
|
```
|
2014-03-31 09:43:45 -04:00
|
|
|
|
2016-01-18 02:21:01 -05:00
|
|
|
| Attribute | Type | Required | Description |
|
|
|
|
| --------- | ---- | -------- | ----------- |
|
2017-04-08 04:54:00 -04:00
|
|
|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
|
2016-01-18 02:21:01 -05:00
|
|
|
| `branch` | string | yes | The name of the branch |
|
2016-07-12 10:31:55 -04:00
|
|
|
| `developers_can_push` | boolean | no | Flag if developers can push to the branch |
|
2016-07-19 04:36:18 -04:00
|
|
|
| `developers_can_merge` | boolean | no | Flag if developers can merge to the branch |
|
2016-01-18 02:21:01 -05:00
|
|
|
|
|
|
|
Example response:
|
2014-03-31 09:43:45 -04:00
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"commit": {
|
2015-02-15 09:01:27 -05:00
|
|
|
"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",
|
2014-03-31 09:43:45 -04:00
|
|
|
"id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
|
2016-10-27 09:26:58 -04:00
|
|
|
"short_id": "7b5c3cc",
|
|
|
|
"title": "add projects API",
|
2014-03-31 09:43:45 -04:00
|
|
|
"message": "add projects API",
|
2015-02-15 09:01:27 -05:00
|
|
|
"parent_ids": [
|
|
|
|
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
|
|
|
|
]
|
2014-03-31 09:43:45 -04:00
|
|
|
},
|
2015-02-15 09:01:27 -05:00
|
|
|
"name": "master",
|
2016-11-28 13:16:15 -05:00
|
|
|
"merged": false,
|
2016-07-12 10:31:55 -04:00
|
|
|
"protected": true,
|
2016-07-19 04:36:18 -04:00
|
|
|
"developers_can_push": true,
|
|
|
|
"developers_can_merge": true
|
2014-03-31 09:43:45 -04:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
## Unprotect repository branch
|
|
|
|
|
2016-01-18 02:21:01 -05:00
|
|
|
Unprotects a single project repository branch. This is an idempotent function,
|
|
|
|
unprotecting an already unprotected repository branch still returns a `200 OK`
|
|
|
|
status code.
|
2014-03-31 09:43:45 -04:00
|
|
|
|
|
|
|
```
|
|
|
|
PUT /projects/:id/repository/branches/:branch/unprotect
|
|
|
|
```
|
|
|
|
|
2016-01-18 02:21:01 -05:00
|
|
|
```bash
|
2017-03-01 12:39:40 -05:00
|
|
|
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/repository/branches/master/unprotect
|
2016-01-18 02:21:01 -05:00
|
|
|
```
|
|
|
|
|
|
|
|
| Attribute | Type | Required | Description |
|
|
|
|
| --------- | ---- | -------- | ----------- |
|
2017-04-08 04:54:00 -04:00
|
|
|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
|
2016-01-18 02:21:01 -05:00
|
|
|
| `branch` | string | yes | The name of the branch |
|
2014-03-31 09:43:45 -04:00
|
|
|
|
2016-01-18 02:21:01 -05:00
|
|
|
Example response:
|
2014-03-31 09:43:45 -04:00
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"commit": {
|
2015-02-15 09:01:27 -05:00
|
|
|
"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",
|
2014-03-31 09:43:45 -04:00
|
|
|
"id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
|
2016-10-27 09:26:58 -04:00
|
|
|
"short_id": "7b5c3cc",
|
|
|
|
"title": "add projects API",
|
2014-03-31 09:43:45 -04:00
|
|
|
"message": "add projects API",
|
2015-02-15 09:01:27 -05:00
|
|
|
"parent_ids": [
|
|
|
|
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
|
|
|
|
]
|
2014-03-31 09:43:45 -04:00
|
|
|
},
|
2015-02-15 09:01:27 -05:00
|
|
|
"name": "master",
|
2016-11-28 13:16:15 -05:00
|
|
|
"merged": false,
|
2016-07-12 10:31:55 -04:00
|
|
|
"protected": false,
|
2016-07-19 04:36:18 -04:00
|
|
|
"developers_can_push": false,
|
|
|
|
"developers_can_merge": false
|
2014-03-31 09:43:45 -04:00
|
|
|
}
|
|
|
|
```
|
2014-04-01 03:44:58 -04:00
|
|
|
|
|
|
|
## Create repository branch
|
|
|
|
|
|
|
|
```
|
|
|
|
POST /projects/:id/repository/branches
|
|
|
|
```
|
|
|
|
|
2016-01-18 02:21:01 -05:00
|
|
|
| Attribute | Type | Required | Description |
|
|
|
|
| --------- | ---- | -------- | ----------- |
|
2017-04-08 04:54:00 -04:00
|
|
|
| `id` | integer | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
|
2017-02-02 09:24:30 -05:00
|
|
|
| `branch` | string | yes | The name of the branch |
|
2016-01-18 02:21:01 -05:00
|
|
|
| `ref` | string | yes | The branch name or commit SHA to create branch from |
|
|
|
|
|
|
|
|
```bash
|
2017-03-01 12:39:40 -05:00
|
|
|
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/branches?branch=newbranch&ref=master"
|
2016-01-18 02:21:01 -05:00
|
|
|
```
|
2014-04-01 03:44:58 -04:00
|
|
|
|
2016-01-18 02:21:01 -05:00
|
|
|
Example response:
|
2014-04-01 03:44:58 -04:00
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
2014-04-05 02:36:47 -04:00
|
|
|
"commit": {
|
|
|
|
"author_email": "john@example.com",
|
2015-02-15 09:01:27 -05:00
|
|
|
"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",
|
2016-10-27 09:26:58 -04:00
|
|
|
"short_id": "7b5c3cc",
|
|
|
|
"title": "add projects API",
|
2015-02-15 09:01:27 -05:00
|
|
|
"message": "add projects API",
|
|
|
|
"parent_ids": [
|
|
|
|
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
|
|
|
|
]
|
2014-04-05 02:36:47 -04:00
|
|
|
},
|
2016-01-18 02:21:01 -05:00
|
|
|
"name": "newbranch",
|
2016-11-28 13:16:15 -05:00
|
|
|
"merged": false,
|
2016-07-12 10:31:55 -04:00
|
|
|
"protected": false,
|
2016-07-19 04:36:18 -04:00
|
|
|
"developers_can_push": false,
|
|
|
|
"developers_can_merge": false
|
2014-04-01 03:44:58 -04:00
|
|
|
}
|
|
|
|
```
|
2014-05-23 08:34:02 -04:00
|
|
|
|
|
|
|
## Delete repository branch
|
|
|
|
|
|
|
|
```
|
|
|
|
DELETE /projects/:id/repository/branches/:branch
|
|
|
|
```
|
|
|
|
|
2016-01-18 02:21:01 -05:00
|
|
|
| Attribute | Type | Required | Description |
|
|
|
|
| --------- | ---- | -------- | ----------- |
|
2017-04-08 04:54:00 -04:00
|
|
|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
|
2016-01-18 02:21:01 -05:00
|
|
|
| `branch` | string | yes | The name of the branch |
|
2014-05-23 08:34:02 -04:00
|
|
|
|
2016-11-24 12:28:52 -05:00
|
|
|
In case of an error, an explaining message is provided.
|
2014-05-23 08:34:02 -04:00
|
|
|
|
2016-01-18 02:21:01 -05:00
|
|
|
```bash
|
2017-03-01 12:39:40 -05:00
|
|
|
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/branches/newbranch"
|
2016-01-18 02:21:01 -05:00
|
|
|
```
|
2014-10-30 11:30:09 -04:00
|
|
|
|
2016-09-21 10:15:12 -04:00
|
|
|
## Delete merged branches
|
|
|
|
|
|
|
|
Will delete all branches that are merged into the project's default branch.
|
|
|
|
|
2017-06-08 06:37:35 -04:00
|
|
|
Protected branches will not be deleted as part of this operation.
|
|
|
|
|
2016-09-21 10:15:12 -04:00
|
|
|
```
|
|
|
|
DELETE /projects/:id/repository/merged_branches
|
|
|
|
```
|
|
|
|
|
|
|
|
| Attribute | Type | Required | Description |
|
|
|
|
| --------- | ---- | -------- | ----------- |
|
2017-04-08 04:54:00 -04:00
|
|
|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
|
2016-09-21 10:15:12 -04:00
|
|
|
|
|
|
|
|
|
|
|
```bash
|
2017-03-01 12:39:40 -05:00
|
|
|
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/merged_branches"
|
2016-09-21 10:15:12 -04:00
|
|
|
```
|