BigW Consortium Gitlab

merge_requests.md 5.34 KB
Newer Older
1 2
## List merge requests

3 4
Get all merge requests for this project. This function takes pagination parameters
`page` and `per_page` to restrict the list of merge requests.
5 6

```
7
GET /projects/:id/merge_requests
8 9 10 11
```

Parameters:

12
+ `id` (required) - The ID of a project
13 14 15 16 17 18 19 20 21 22 23 24 25

```json
[
    {
        "id":1,
        "target_branch":"master",
        "source_branch":"test1",
        "project_id":3,
        "title":"test1",
        "closed":true,
        "merged":false,
        "author":{
            "id":1,
26
            "username": "admin",
27 28 29 30 31 32 33
            "email":"admin@local.host",
            "name":"Administrator",
            "blocked":false,
            "created_at":"2012-04-29T08:46:00Z"
        },
        "assignee":{
            "id":1,
34
            "username": "admin",
35 36 37 38 39 40 41 42 43
            "email":"admin@local.host",
            "name":"Administrator",
            "blocked":false,
            "created_at":"2012-04-29T08:46:00Z"
        }
    }
]
```

44
Return values:
45

46 47 48 49 50 51 52 53
+ `200 Ok` on success and the list of merge requests
+ `401 Unauthorized` if user is not authenticated
+ `404 Not Found` if project ID not found


## Get single MR

Shows information about a single merge request.
54 55

```
56
GET /projects/:id/merge_request/:merge_request_id
57 58 59 60
```

Parameters:

61
+ `id` (required) - The ID of a project
62 63 64 65 66 67 68 69 70 71 72 73 74
+ `merge_request_id` (required) - The ID of MR

```json
{
    "id":1,
    "target_branch":"master",
    "source_branch":"test1",
    "project_id":3,
    "title":"test1",
    "closed":true,
    "merged":false,
    "author":{
        "id":1,
75
        "username": "admin",
76 77 78 79 80 81 82
        "email":"admin@local.host",
        "name":"Administrator",
        "blocked":false,
        "created_at":"2012-04-29T08:46:00Z"
    },
    "assignee":{
        "id":1,
83
        "username": "admin",
84 85 86 87 88 89 90 91
        "email":"admin@local.host",
        "name":"Administrator",
        "blocked":false,
        "created_at":"2012-04-29T08:46:00Z"
    }
}
```

92 93 94 95 96 97
Return values:

+ `200 Ok` on success and the single merge request
+ `401 Unauthorized` if user is not authenticated
+ `404 Not Found` if project ID or merge request ID not found

98 99 100

## Create MR

101
Creates a new merge request.
102 103

```
104
POST /projects/:id/merge_requests
105 106 107 108
```

Parameters:

109
+ `id` (required) - The ID of a project
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
+ `source_branch` (required) - The source branch
+ `target_branch` (required) - The target branch
+ `assignee_id`              - Assignee user ID
+ `title` (required)         - Title of MR

```json
{
    "id":1,
    "target_branch":"master",
    "source_branch":"test1",
    "project_id":3,
    "title":"test1",
    "closed":true,
    "merged":false,
    "author":{
        "id":1,
126
        "username": "admin",
127 128 129 130 131 132 133
        "email":"admin@local.host",
        "name":"Administrator",
        "blocked":false,
        "created_at":"2012-04-29T08:46:00Z"
    },
    "assignee":{
        "id":1,
134
        "username": "admin",
135 136 137 138 139 140 141 142
        "email":"admin@local.host",
        "name":"Administrator",
        "blocked":false,
        "created_at":"2012-04-29T08:46:00Z"
    }
}
```

143 144 145 146 147 148 149 150 151
Return values:

+ `201 Created` on success and the created merge request
+ `400 Bad Request` if one of the required attributes is missing
+ `401 Unauthorize` if user is not authenticated or not allowed
+ `403 Forbidden` if user is not allowed to create a merge request
+ `404 Not Found` if project ID not found or something else fails


152 153
## Update MR

154
Updates an existing merge request. You can change branches, title, or even close the MR.
155 156

```
157
PUT /projects/:id/merge_request/:merge_request_id
158 159 160 161
```

Parameters:

162
+ `id` (required)               - The ID of a project
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181
+ `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
+ `closed`                      - Status of MR. true - closed


```json
{
    "id":1,
    "target_branch":"master",
    "source_branch":"test1",
    "project_id":3,
    "title":"test1",
    "closed":true,
    "merged":false,
    "author":{
        "id":1,
182
        "username": "admin",
183 184 185 186 187 188 189
        "email":"admin@local.host",
        "name":"Administrator",
        "blocked":false,
        "created_at":"2012-04-29T08:46:00Z"
    },
    "assignee":{
        "id":1,
190
        "username": "admin",
191 192 193 194 195 196 197
        "email":"admin@local.host",
        "name":"Administrator",
        "blocked":false,
        "created_at":"2012-04-29T08:46:00Z"
    }
}
```
198 199 200 201 202 203 204 205 206

Return values:

+ `200 Ok` on success and the updated merge request
+ `401 Unauthorize` if user is not authenticated or not allowed
+ `403 Forbidden` if user is not allowed to update the merge request
+ `404 Not Found` if project ID or merge request ID not found


207 208
## Post comment to MR

209
Adds a comment to a merge request.
210 211

```
212
POST /projects/:id/merge_request/:merge_request_id/comments
213 214 215 216
```

Parameters:

217
+ `id` (required) - The ID of a project
218
+ `merge_request_id` (required) - ID of merge request
219 220 221 222 223 224 225
+ `note` (required) - Text of comment


```json
{
    "author":{
        "id":1,
226
        "username": "admin",
227 228 229 230 231 232 233 234
        "email":"admin@local.host",
        "name":"Administrator",
        "blocked":false,
        "created_at":"2012-04-29T08:46:00Z"
    },
    "note":"text1"
}
```
235 236 237 238 239 240 241

Return values:

+ `201 Created` on success and the new comment
+ `400 Bad Request` if the required attribute note is not given
+ `401 Unauthorized` if user is not authenticated
+ `404 Not Found` if project ID or merge request ID not found