BigW Consortium Gitlab

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

## Get single repository branch

Get a single project repository branch.

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

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

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

Example response:
64 65 66

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

## Protect repository branch

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

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

97
```bash
98
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
99
```
100

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

Example response:
109 110 111 112

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

## Unprotect repository branch

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

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

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

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

151
Example response:
152 153 154 155

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

## Create repository branch

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

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

191
Example response:
192 193 194

```json
{
195 196
  "commit": {
    "author_email": "john@example.com",
197 198 199 200 201 202 203 204 205 206
    "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"
    ]
207
  },
208
  "name": "newbranch",
209
  "protected": false,
210 211
  "developers_can_push": false,
  "developers_can_merge": false
212 213
}
```
214

215 216
It returns `200` if it succeeds or `400` if failed with an error message
explaining the reason.
217

218 219 220 221 222 223
## Delete repository branch

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

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

229 230
It returns `200` if it succeeds, `404` if the branch to be deleted does not exist
or `400` for other reasons. In case of an error, an explaining message is provided.
231

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

236
Example response:
237 238 239

```json
{
240
  "branch_name": "newbranch"
241 242
}
```