BigW Consortium Gitlab

branches.md 6.81 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 37
      "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
      "message": "add projects API",
38 39 40
      "parent_ids": [
        "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
      ]
41 42 43
    }
  },
  ...
44 45 46 47 48 49 50 51 52 53 54
]
```

## Get single repository branch

Get a single project repository branch.

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

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

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

Example response:
65 66 67

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

## Protect repository branch

91 92 93
Protects a single project repository branch. This is an idempotent function,
protecting an already protected repository branch still returns a `200 OK`
status code.
94 95 96 97 98

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

99
```bash
100
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
101
```
102

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

Example response:
111 112 113 114

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

## Unprotect repository branch

137 138 139
Unprotects a single project repository branch. This is an idempotent function,
unprotecting an already unprotected repository branch still returns a `200 OK`
status code.
140 141 142 143 144

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

145
```bash
146
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches/master/unprotect
147 148 149 150 151 152
```

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

154
Example response:
155 156 157 158

```json
{
  "commit": {
159 160 161 162 163 164
    "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",
165 166
    "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
    "message": "add projects API",
167 168 169
    "parent_ids": [
      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
    ]
170
  },
171
  "name": "master",
172
  "merged": false,
173
  "protected": false,
174 175
  "developers_can_push": false,
  "developers_can_merge": false
176 177
}
```
178 179 180 181 182 183 184

## Create repository branch

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

185 186 187 188 189 190 191
| 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
192
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/branches?branch_name=newbranch&ref=master"
193
```
194

195
Example response:
196 197 198

```json
{
199 200
  "commit": {
    "author_email": "john@example.com",
201 202 203 204 205 206 207 208 209 210
    "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",
    "message": "add projects API",
    "parent_ids": [
      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
    ]
211
  },
212
  "name": "newbranch",
213
  "merged": false,
214
  "protected": false,
215 216
  "developers_can_push": false,
  "developers_can_merge": false
217 218
}
```
219 220 221 222 223 224 225

## Delete repository branch

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

226 227 228 229
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id`      | integer | yes | The ID of a project |
| `branch`  | string  | yes | The name of the branch |
230

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

233
```bash
234
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/branches/newbranch"
235
```
236

237
Example response:
238 239 240

```json
{
241
  "branch_name": "newbranch"
242 243
}
```
244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260

## 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"
```