branches.md 7.11 KB
Newer Older
1 2 3 4 5 6 7 8 9 10
# Branches

## List repository branches

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

```
GET /projects/:id/repository/branches
```

11 12 13
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
14

15
```bash
16
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches
17 18 19
```

Example response:
20 21 22 23

```json
[
  {
24
    "name": "master",
25
    "merged": false,
26
    "protected": true,
27
    "developers_can_push": false,
28
    "developers_can_merge": false,
29
    "commit": {
30 31 32 33 34 35
      "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",
36
      "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
37 38
      "short_id": "7b5c3cc",
      "title": "add projects API",
39
      "message": "add projects API",
40 41 42
      "parent_ids": [
        "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
      ]
43 44 45
    }
  },
  ...
46 47 48 49 50 51 52 53 54 55 56
]
```

## Get single repository branch

Get a single project repository branch.

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

57 58 59 60
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `branch` | string | yes | The name of the branch |
61

62
```bash
63
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches/master
64 65 66
```

Example response:
67 68 69

```json
{
70
  "name": "master",
71
  "merged": false,
72
  "protected": true,
73
  "developers_can_push": false,
74
  "developers_can_merge": false,
75
  "commit": {
76 77 78 79 80 81
    "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",
82
    "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
83 84
    "short_id": "7b5c3cc",
    "title": "add projects API",
85
    "message": "add projects API",
86 87 88
    "parent_ids": [
      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
    ]
89
  }
90 91 92 93 94
}
```

## Protect repository branch

95 96 97
Protects a single project repository branch. This is an idempotent function,
protecting an already protected repository branch still returns a `200 OK`
status code.
98 99 100 101 102

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

103
```bash
104
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches/master/protect?developers_can_push=true&developers_can_merge=true
105
```
106

107 108 109 110
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `branch` | string | yes | The name of the branch |
111
| `developers_can_push` | boolean | no | Flag if developers can push to the branch |
112
| `developers_can_merge` | boolean | no | Flag if developers can merge to the branch |
113 114

Example response:
115 116 117 118

```json
{
  "commit": {
119 120 121 122 123 124
    "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",
125
    "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
126 127
    "short_id": "7b5c3cc",
    "title": "add projects API",
128
    "message": "add projects API",
129 130 131
    "parent_ids": [
      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
    ]
132
  },
133
  "name": "master",
134
  "merged": false,
135
  "protected": true,
136 137
  "developers_can_push": true,
  "developers_can_merge": true
138 139 140 141 142
}
```

## Unprotect repository branch

143 144 145
Unprotects a single project repository branch. This is an idempotent function,
unprotecting an already unprotected repository branch still returns a `200 OK`
status code.
146 147 148 149 150

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

151
```bash
152
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches/master/unprotect
153 154 155 156 157 158
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `branch` | string | yes | The name of the branch |
159

160
Example response:
161 162 163 164

```json
{
  "commit": {
165 166 167 168 169 170
    "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",
171
    "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
172 173
    "short_id": "7b5c3cc",
    "title": "add projects API",
174
    "message": "add projects API",
175 176 177
    "parent_ids": [
      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
    ]
178
  },
179
  "name": "master",
180
  "merged": false,
181
  "protected": false,
182 183
  "developers_can_push": false,
  "developers_can_merge": false
184 185
}
```
186 187 188 189 190 191 192

## Create repository branch

```
POST /projects/:id/repository/branches
```

193 194 195 196 197 198 199
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id`          | integer | yes | The ID of a project |
| `branch_name` | string  | yes | The name of the branch |
| `ref`         | string  | yes | The branch name or commit SHA to create branch from |

```bash
200
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/branches?branch_name=newbranch&ref=master"
201
```
202

203
Example response:
204 205 206

```json
{
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
207 208
  "commit": {
    "author_email": "john@example.com",
209 210 211 212 213 214
    "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",
215 216
    "short_id": "7b5c3cc",
    "title": "add projects API",
217 218 219 220
    "message": "add projects API",
    "parent_ids": [
      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
    ]
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
221
  },
222
  "name": "newbranch",
223
  "merged": false,
224
  "protected": false,
225 226
  "developers_can_push": false,
  "developers_can_merge": false
227 228
}
```
229 230 231 232 233 234 235

## Delete repository branch

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

236 237 238 239
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id`      | integer | yes | The ID of a project |
| `branch`  | string  | yes | The name of the branch |
240

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

243
```bash
244
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/branches/newbranch"
245
```
246

247
Example response:
248 249 250

```json
{
251
  "branch_name": "newbranch"
252 253
}
```
254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270

## Delete merged branches

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

```
DELETE /projects/:id/repository/merged_branches
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id`      | integer | yes | The ID of a project |


```bash
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/merged_branches"
```