merge_requests.md 9.21 KB
Newer Older
Marin Jankovski's avatar
Marin Jankovski committed
1 2
# Merge requests

Valeriy Sizov's avatar
Valeriy Sizov committed
3 4
## List merge requests

5 6 7
Get all merge requests for this project. 
The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, or `merged`) or all of them (`all`). 
The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests.
Valeriy Sizov's avatar
Valeriy Sizov committed
8 9

```
10
GET /projects/:id/merge_requests
11 12
GET /projects/:id/merge_requests?state=opened
GET /projects/:id/merge_requests?state=all
13
GET /projects/:id/merge_requests?iid=42
Valeriy Sizov's avatar
Valeriy Sizov committed
14 15 16 17
```

Parameters:

18
- `id` (required) - The ID of a project
19
- `iid` (optional) - Return the request having the given `iid`
20
- `state` (optional) - Return `all` requests or just those that are `merged`, `opened` or `closed`
21 22
- `order_by` (optional) - Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`
- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`
Valeriy Sizov's avatar
Valeriy Sizov committed
23 24 25

```json
[
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
26 27 28 29 30 31 32 33 34 35 36 37 38
  {
    "id": 1,
    "iid": 1,
    "target_branch": "master",
    "source_branch": "test1",
    "project_id": 3,
    "title": "test1",
    "state": "opened",
    "upvotes": 0,
    "downvotes": 0,
    "author": {
      "id": 1,
      "username": "admin",
39
      "email": "admin@example.com",
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
40 41 42 43 44 45 46
      "name": "Administrator",
      "state": "active",
      "created_at": "2012-04-29T08:46:00Z"
    },
    "assignee": {
      "id": 1,
      "username": "admin",
47
      "email": "admin@example.com",
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
48 49 50
      "name": "Administrator",
      "state": "active",
      "created_at": "2012-04-29T08:46:00Z"
51
    },
52 53
    "description":"fixed login page css paddings",
    "work_in_progress": false
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
54
  }
Valeriy Sizov's avatar
Valeriy Sizov committed
55 56 57
]
```

58 59 60
## Get single MR

Shows information about a single merge request.
Valeriy Sizov's avatar
Valeriy Sizov committed
61 62

```
63
GET /projects/:id/merge_request/:merge_request_id
Valeriy Sizov's avatar
Valeriy Sizov committed
64 65 66 67
```

Parameters:

68 69
- `id` (required) - The ID of a project
- `merge_request_id` (required) - The ID of MR
Valeriy Sizov's avatar
Valeriy Sizov committed
70 71 72

```json
{
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
73 74 75 76 77 78 79 80 81 82 83 84
  "id": 1,
  "iid": 1,
  "target_branch": "master",
  "source_branch": "test1",
  "project_id": 3,
  "title": "test1",
  "state": "merged",
  "upvotes": 0,
  "downvotes": 0,
  "author": {
    "id": 1,
    "username": "admin",
85
    "email": "admin@example.com",
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
86 87 88 89 90 91 92
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  },
  "assignee": {
    "id": 1,
    "username": "admin",
93
    "email": "admin@example.com",
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
94 95 96
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
97
  },
98 99
  "description":"fixed login page css paddings",
  "work_in_progress": false
Valeriy Sizov's avatar
Valeriy Sizov committed
100 101 102
}
```

103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122
## Get single MR changes

Shows information about the merge request including its files and changes

```
GET /projects/:id/merge_request/:merge_request_id/changes
```

Parameters:

- `id` (required) - The ID of a project
- `merge_request_id` (required) - The ID of MR

```json
{
  "id": 21,
  "iid": 1,
  "project_id": 4,
  "title": "Blanditiis beatae suscipit hic assumenda et molestias nisi asperiores repellat et.",
  "description": "Qui voluptatibus placeat ipsa alias quasi. Deleniti rem ut sint. Optio velit qui distinctio.",
123
  "work_in_progress": false,
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173
  "state": "reopened",
  "created_at": "2015-02-02T19:49:39.159Z",
  "updated_at": "2015-02-02T20:08:49.959Z",
  "target_branch": "secret_token",
  "source_branch": "version-1-9",
  "upvotes": 0,
  "downvotes": 0,
  "author": {
    "name": "Chad Hamill",
    "username": "jarrett",
    "id": 5,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/b95567800f828948baf5f4160ebb2473?s=40&d=identicon"
  },
  "assignee": {
    "name": "Administrator",
    "username": "root",
    "id": 1,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40&d=identicon"
  },
  "source_project_id": 4,
  "target_project_id": 4,
  "labels": [ ],
  "milestone": {
    "id": 5,
    "iid": 1,
    "project_id": 4,
    "title": "v2.0",
    "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.",
    "state": "closed",
    "created_at": "2015-02-02T19:49:26.013Z",
    "updated_at": "2015-02-02T19:49:26.013Z",
    "due_date": null
  },
  "files": [
    {
    "old_path": "VERSION",
    "new_path": "VERSION",
    "a_mode": "100644",
    "b_mode": "100644",
    "diff": "--- a/VERSION\ +++ b/VERSION\ @@ -1 +1 @@\ -1.9.7\ +1.9.8",
    "new_file": false,
    "renamed_file": false,
    "deleted_file": false
    }
  ]
}
```

Valeriy Sizov's avatar
Valeriy Sizov committed
174 175
## Create MR

176
Creates a new merge request.
Valeriy Sizov's avatar
Valeriy Sizov committed
177 178

```
179
POST /projects/:id/merge_requests
Valeriy Sizov's avatar
Valeriy Sizov committed
180 181 182 183
```

Parameters:

184 185 186 187 188
- `id` (required)                - The ID of a project
- `source_branch` (required)     - The source branch
- `target_branch` (required)     - The target branch
- `assignee_id` (optional)       - Assignee user ID
- `title` (required)             - Title of MR
189
- `description` (optional)       - Description of MR
190
- `target_project_id` (optional) - The target project (numeric id)
191
- `labels` (optional)            - Labels for MR as a comma-separated list
Valeriy Sizov's avatar
Valeriy Sizov committed
192 193 194

```json
{
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
195 196 197 198 199 200 201 202 203 204 205
  "id": 1,
  "target_branch": "master",
  "source_branch": "test1",
  "project_id": 3,
  "title": "test1",
  "state": "opened",
  "upvotes": 0,
  "downvotes": 0,
  "author": {
    "id": 1,
    "username": "admin",
206
    "email": "admin@example.com",
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
207 208 209 210 211 212 213
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  },
  "assignee": {
    "id": 1,
    "username": "admin",
214
    "email": "admin@example.com",
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
215 216 217
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
218 219
  },
  "description":"fixed login page css paddings"
Valeriy Sizov's avatar
Valeriy Sizov committed
220 221 222
}
```

223 224 225
If the operation is successful, 200 and the newly created merge request is returned.
If an error occurs, an error number and a message explaining the reason is returned.

Valeriy Sizov's avatar
Valeriy Sizov committed
226 227
## Update MR

228
Updates an existing merge request. You can change the target branch, title, or even close the MR.
Valeriy Sizov's avatar
Valeriy Sizov committed
229 230

```
231
PUT /projects/:id/merge_request/:merge_request_id
Valeriy Sizov's avatar
Valeriy Sizov committed
232 233 234 235
```

Parameters:

236 237 238 239 240
- `id` (required)               - The ID of a project
- `merge_request_id` (required) - ID of MR
- `target_branch`               - The target branch
- `assignee_id`                 - Assignee user ID
- `title`                       - Title of MR
241
- `description`                 - Description of MR
242
- `state_event`                 - New state (close|reopen|merge)
243
- `labels` (optional)           - Labels for MR as a comma-separated list
Valeriy Sizov's avatar
Valeriy Sizov committed
244 245 246

```json
{
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
247 248 249 250
  "id": 1,
  "target_branch": "master",
  "project_id": 3,
  "title": "test1",
251
  "description": "description1",
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
252 253 254 255 256 257
  "state": "opened",
  "upvotes": 0,
  "downvotes": 0,
  "author": {
    "id": 1,
    "username": "admin",
258
    "email": "admin@example.com",
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
259 260 261 262 263 264 265
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  },
  "assignee": {
    "id": 1,
    "username": "admin",
266
    "email": "admin@example.com",
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
267 268 269 270
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  }
Valeriy Sizov's avatar
Valeriy Sizov committed
271 272
}
```
273

274 275 276
If the operation is successful, 200 and the updated merge request is returned.
If an error occurs, an error number and a message explaining the reason is returned.

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
277 278
## Accept MR

279
Merge changes submitted with MR using this API.
280

281
If merge success you get `200 OK`.
282

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
283
If it has some conflicts and can not be merged - you get 405 and error message 'Branch cannot be merged'
284

285
If merge request is already merged or closed - you get 405 and error message 'Method Not Allowed'
286

287
If you don't have permissions to accept this merge request - you'll get a 401
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
288 289 290 291 292 293 294

```
PUT /projects/:id/merge_request/:merge_request_id/merge
```

Parameters:

295 296 297
- `id` (required)                   - The ID of a project
- `merge_request_id` (required)     - ID of MR
- `merge_commit_message` (optional) - Custom merge commit message
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
298 299 300 301 302 303 304 305 306 307 308 309 310 311

```json
{
  "id": 1,
  "target_branch": "master",
  "source_branch": "test1",
  "project_id": 3,
  "title": "test1",
  "state": "merged",
  "upvotes": 0,
  "downvotes": 0,
  "author": {
    "id": 1,
    "username": "admin",
312
    "email": "admin@example.com",
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
313 314 315 316 317 318 319
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  },
  "assignee": {
    "id": 1,
    "username": "admin",
320
    "email": "admin@example.com",
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
321 322 323 324 325 326 327
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  }
}
```

Valeriy Sizov's avatar
Valeriy Sizov committed
328 329
## Post comment to MR

330
Adds a comment to a merge request.
Valeriy Sizov's avatar
Valeriy Sizov committed
331 332

```
333
POST /projects/:id/merge_request/:merge_request_id/comments
Valeriy Sizov's avatar
Valeriy Sizov committed
334 335 336 337
```

Parameters:

338 339 340
- `id` (required)               - The ID of a project
- `merge_request_id` (required) - ID of merge request
- `note` (required)             - Text of comment
Valeriy Sizov's avatar
Valeriy Sizov committed
341 342 343

```json
{
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
344
  "note": "text1"
Valeriy Sizov's avatar
Valeriy Sizov committed
345 346
}
```
347 348 349 350 351 352 353 354 355 356 357

## Get the comments on a MR

Gets all the comments associated with a merge request.

```
GET /projects/:id/merge_request/:merge_request_id/comments
```

Parameters:

358 359
- `id` (required)               - The ID of a project
- `merge_request_id` (required) - ID of merge request
360 361 362

```json
[
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
363 364 365 366 367
  {
    "note": "this is the 1st comment on the 2merge merge request",
    "author": {
      "id": 11,
      "username": "admin",
368
      "email": "admin@example.com",
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
369 370 371 372 373 374
      "name": "Administrator",
      "state": "active",
      "created_at": "2014-03-06T08:17:35.000Z"
    }
  },
  {
375
    "note": "Status changed to closed",
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
376 377 378
    "author": {
      "id": 11,
      "username": "admin",
379
      "email": "admin@example.com",
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
380 381 382
      "name": "Administrator",
      "state": "active",
      "created_at": "2014-03-06T08:17:35.000Z"
383
    }
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
384
  }
385 386
]
```
387

388
## Comments on merge requets
389 390

Comments are done via the notes resource.