BigW Consortium Gitlab

branches.md 7.96 KB
Newer Older
1
# Branches API
2 3 4 5

## List repository branches

Get a list of repository branches from a project, sorted by name alphabetically.
6 7
This endpoint can be accessed without authentication if the repository is
publicly accessible.
8 9 10 11 12

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

13 14
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
15
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
16

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

Example response:
22 23 24 25

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

## Get single repository branch

53 54
Get a single project repository branch. This endpoint can be accessed without
authentication if the repository is publicly accessible.
55 56 57 58 59

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

60 61
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
62
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
63
| `branch` | string | yes | The name of the branch |
64

65
```bash
66
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/repository/branches/master
67 68 69
```

Example response:
70 71 72

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

## Protect repository branch

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

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

106
```bash
107
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
108
```
109

110 111
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
112
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
113
| `branch` | string | yes | The name of the branch |
114
| `developers_can_push` | boolean | no | Flag if developers can push to the branch |
115
| `developers_can_merge` | boolean | no | Flag if developers can merge to the branch |
116 117

Example response:
118 119 120 121

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

## Unprotect repository branch

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

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

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

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
160
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
161
| `branch` | string | yes | The name of the branch |
162

163
Example response:
164 165 166 167

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

## Create repository branch

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

196 197
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
198
| `id`          | integer | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
199
| `branch` | string  | yes | The name of the branch |
200 201 202
| `ref`         | string  | yes | The branch name or commit SHA to create branch from |

```bash
203
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/branches?branch=newbranch&ref=master"
204
```
205

206
Example response:
207 208 209

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

## Delete repository branch

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

239 240
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
241
| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
242
| `branch`  | string  | yes | The name of the branch |
243

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

246
```bash
247
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/branches/newbranch"
248
```
249

250 251 252 253
## Delete merged branches

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

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

256 257 258 259 260 261
```
DELETE /projects/:id/repository/merged_branches
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
262
| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
263 264 265


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