BigW Consortium Gitlab

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

## 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 254 255 256 257 258 259
## 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 |
| --------- | ---- | -------- | ----------- |
260
| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
261 262 263


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