merge_requests.md 6.43 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 8 9
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
10 11

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

Parameters:

19
+ `id` (required) - The ID of a project
20
+ `state` (optional) - Return `all` requests or just those that are `merged`, `opened` or `closed`
Valeriy Sizov's avatar
Valeriy Sizov committed
21 22 23

```json
[
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
  {
    "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",
      "email": "admin@local.host",
      "name": "Administrator",
      "state": "active",
      "created_at": "2012-04-29T08:46:00Z"
    },
    "assignee": {
      "id": 1,
      "username": "admin",
      "email": "admin@local.host",
      "name": "Administrator",
      "state": "active",
      "created_at": "2012-04-29T08:46:00Z"
Valeriy Sizov's avatar
Valeriy Sizov committed
49
    }
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
50
  }
Valeriy Sizov's avatar
Valeriy Sizov committed
51 52 53
]
```

54 55 56 57

## Get single MR

Shows information about a single merge request.
Valeriy Sizov's avatar
Valeriy Sizov committed
58 59

```
60
GET /projects/:id/merge_request/:merge_request_id
Valeriy Sizov's avatar
Valeriy Sizov committed
61 62 63 64
```

Parameters:

65
+ `id` (required) - The ID of a project
Valeriy Sizov's avatar
Valeriy Sizov committed
66 67 68 69
+ `merge_request_id` (required) - The ID of MR

```json
{
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
  "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",
    "email": "admin@local.host",
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  },
  "assignee": {
    "id": 1,
    "username": "admin",
    "email": "admin@local.host",
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  }
Valeriy Sizov's avatar
Valeriy Sizov committed
95 96 97 98 99 100
}
```


## Create MR

101
Creates a new merge request.
Valeriy Sizov's avatar
Valeriy Sizov committed
102 103

```
104
POST /projects/:id/merge_requests
Valeriy Sizov's avatar
Valeriy Sizov committed
105 106 107 108
```

Parameters:

109
+ `id` (required) - The ID of a project
110 111 112 113 114
+ `source_branch` (required)     - The source branch
+ `target_branch` (required)     - The target branch
+ `assignee_id` (optional)       - Assignee user ID
+ `title` (required)             - Title of MR
+ `target_project_id` (optional) - The target project (numeric id)
Valeriy Sizov's avatar
Valeriy Sizov committed
115 116 117

```json
{
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141
  "id": 1,
  "target_branch": "master",
  "source_branch": "test1",
  "project_id": 3,
  "title": "test1",
  "state": "opened",
  "upvotes": 0,
  "downvotes": 0,
  "author": {
    "id": 1,
    "username": "admin",
    "email": "admin@local.host",
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  },
  "assignee": {
    "id": 1,
    "username": "admin",
    "email": "admin@local.host",
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  }
Valeriy Sizov's avatar
Valeriy Sizov committed
142 143 144
}
```

145

Valeriy Sizov's avatar
Valeriy Sizov committed
146 147
## Update MR

148
Updates an existing merge request. You can change branches, title, or even close the MR.
Valeriy Sizov's avatar
Valeriy Sizov committed
149 150

```
151
PUT /projects/:id/merge_request/:merge_request_id
Valeriy Sizov's avatar
Valeriy Sizov committed
152 153 154 155
```

Parameters:

156
+ `id` (required)               - The ID of a project
Valeriy Sizov's avatar
Valeriy Sizov committed
157 158 159 160 161
+ `merge_request_id` (required) - ID of MR
+ `source_branch`               - The source branch
+ `target_branch`               - The target branch
+ `assignee_id`                 - Assignee user ID
+ `title`                       - Title of MR
162
+ `state_event`                 - New state (close|reopen|merge)
Valeriy Sizov's avatar
Valeriy Sizov committed
163 164 165

```json
{
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189
  "id": 1,
  "target_branch": "master",
  "source_branch": "test1",
  "project_id": 3,
  "title": "test1",
  "state": "opened",
  "upvotes": 0,
  "downvotes": 0,
  "author": {
    "id": 1,
    "username": "admin",
    "email": "admin@local.host",
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  },
  "assignee": {
    "id": 1,
    "username": "admin",
    "email": "admin@local.host",
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  }
Valeriy Sizov's avatar
Valeriy Sizov committed
190 191
}
```
192 193


Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241
## Accept MR

Merge changes submitted with MR usign this API.
If merge success you get 200 OK.
If it has some conflicts and can not be merged - you get 405 and error message 'Branch cannot be merged'
If merge request is already merged or closed - you get 405 and error message 'Method Not Allowed' 
If you dont have permissions to accept this merge request - you get 401

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

Parameters:

+ `id` (required)               - The ID of a project
+ `merge_request_id` (required) - ID of MR
+ `merge_commit_message` (optional) - Custom merge commit message

```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",
    "email": "admin@local.host",
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  },
  "assignee": {
    "id": 1,
    "username": "admin",
    "email": "admin@local.host",
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  }
}
```


Valeriy Sizov's avatar
Valeriy Sizov committed
242 243
## Post comment to MR

244
Adds a comment to a merge request.
Valeriy Sizov's avatar
Valeriy Sizov committed
245 246

```
247
POST /projects/:id/merge_request/:merge_request_id/comments
Valeriy Sizov's avatar
Valeriy Sizov committed
248 249 250 251
```

Parameters:

252
+ `id` (required) - The ID of a project
253
+ `merge_request_id` (required) - ID of merge request
Valeriy Sizov's avatar
Valeriy Sizov committed
254 255 256 257 258
+ `note` (required) - Text of comment


```json
{
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
259 260 261 262 263 264 265 266 267
  "author": {
    "id": 1,
    "username": "admin",
    "email": "admin@local.host",
    "name": "Administrator",
    "blocked": false,
    "created_at": "2012-04-29T08:46:00Z"
  },
  "note": "text1"
Valeriy Sizov's avatar
Valeriy Sizov committed
268 269
}
```
270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286


## 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:

+ `id` (required) - The ID of a project
+ `merge_request_id` (required) - ID of merge request

```json
[
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306
  {
    "note": "this is the 1st comment on the 2merge merge request",
    "author": {
      "id": 11,
      "username": "admin",
      "email": "admin@local.host",
      "name": "Administrator",
      "state": "active",
      "created_at": "2014-03-06T08:17:35.000Z"
    }
  },
  {
    "note": "_Status changed to closed_",
    "author": {
      "id": 11,
      "username": "admin",
      "email": "admin@local.host",
      "name": "Administrator",
      "state": "active",
      "created_at": "2014-03-06T08:17:35.000Z"
307
    }
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
308
  }
309 310
]
```
311 312 313 314

## Comments on issues

Comments are done via the notes resource.