diff options
Diffstat (limited to 'doc/api/merge_requests.md')
-rw-r--r-- | doc/api/merge_requests.md | 234 |
1 files changed, 180 insertions, 54 deletions
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index f4167403c2c..7b005591545 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -11,6 +11,7 @@ GET /projects/:id/merge_requests GET /projects/:id/merge_requests?state=opened GET /projects/:id/merge_requests?state=all GET /projects/:id/merge_requests?iid=42 +GET /projects/:id/merge_requests?iid[]=42&iid[]=43 ``` Parameters: @@ -270,17 +271,18 @@ Creates a new merge request. POST /projects/:id/merge_requests ``` -Parameters: - -- `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 -- `description` (optional) - Description of MR -- `target_project_id` (optional) - The target project (numeric id) -- `labels` (optional) - Labels for MR as a comma-separated list -- `milestone_id` (optional) - Milestone ID +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | string | yes | The ID of a project | +| `source_branch` | string | yes | The source branch | +| `target_branch` | string | yes | The target branch | +| `title` | string | yes | Title of MR | +| `assignee_id` | integer | no | Assignee user ID | +| `description` | string | no | Description of MR | +| `target_project_id` | integer | no | The target project (numeric id) | +| `labels` | string | no | Labels for MR as a comma-separated list | +| `milestone_id` | integer | no | The ID of a milestone | +| `remove_source_branch` | boolean | no | Flag indicating if a merge request should remove the source branch when merging | ```json { @@ -337,9 +339,6 @@ Parameters: } ``` -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. - ## Update MR Updates an existing merge request. You can change the target branch, title, or even close the MR. @@ -348,17 +347,19 @@ Updates an existing merge request. You can change the target branch, title, or e PUT /projects/:id/merge_requests/:merge_request_id ``` -Parameters: - -- `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 -- `description` - Description of MR -- `state_event` - New state (close|reopen|merge) -- `labels` (optional) - Labels for MR as a comma-separated list -- `milestone_id` (optional) - Milestone ID +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | string | yes | The ID of a project | +| `merge_request_id` | integer | yes | The ID of a merge request | +| `source_branch` | string | yes | The source branch | +| `target_branch` | string | yes | The target branch | +| `title` | string | yes | Title of MR | +| `assignee_id` | integer | no | Assignee user ID | +| `description` | string | no | Description of MR | +| `target_project_id` | integer | no | The target project (numeric id) | +| `labels` | string | no | Labels for MR as a comma-separated list | +| `milestone_id` | integer | no | The ID of a milestone | +| `remove_source_branch` | boolean | no | Flag indicating if a merge request should remove the source branch when merging | ```json { @@ -414,14 +415,9 @@ Parameters: } ``` -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. - ## Delete a merge request Only for admins and project owners. Soft deletes the merge request in question. -If the operation is successful, a status code `200` is returned. In case you cannot -destroy this merge request, or it is not present, code `404` is given. ``` DELETE /projects/:id/merge_requests/:merge_request_id @@ -433,22 +429,21 @@ DELETE /projects/:id/merge_requests/:merge_request_id | `merge_request_id` | integer | yes | The ID of a project's merge request | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/merge_request/85 +curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/merge_requests/85 ``` ## Accept MR Merge changes submitted with MR using this API. -If the merge succeeds you'll get a `200 OK`. -If it has some conflicts and can not be merged - you'll get a 405 and the error message 'Branch cannot be merged' +If it has some conflicts and can not be merged - you'll get a `405` and the error message 'Branch cannot be merged' -If merge request is already merged or closed - you'll get a 406 and the error message 'Method Not Allowed' +If merge request is already merged or closed - you'll get a `406` and the error message 'Method Not Allowed' -If the `sha` parameter is passed and does not match the HEAD of the source - you'll get a 409 and the error message 'SHA does not match HEAD of source branch' +If the `sha` parameter is passed and does not match the HEAD of the source - you'll get a `409` and the error message 'SHA does not match HEAD of source branch' -If you don't have permissions to accept this merge request - you'll get a 401 +If you don't have permissions to accept this merge request - you'll get a `401` ``` PUT /projects/:id/merge_requests/:merge_request_id/merge @@ -518,15 +513,13 @@ Parameters: } ``` -## Cancel Merge When Build Succeeds - -If successful you'll get `200 OK`. +## Cancel Merge When Pipeline Succeeds -If you don't have permissions to accept this merge request - you'll get a 401 +If you don't have permissions to accept this merge request - you'll get a `401` -If the merge request is already merged or closed - you get 405 and error message 'Method Not Allowed' +If the merge request is already merged or closed - you get `405` and error message 'Method Not Allowed' -In case the merge request is not set to be merged when the build succeeds, you'll also get a 406 error. +In case the merge request is not set to be merged when the build succeeds, you'll also get a `406` error. ``` PUT /projects/:id/merge_requests/:merge_request_id/cancel_merge_when_build_succeeds ``` @@ -670,11 +663,8 @@ Example response when an external issue tracker (e.g. JIRA) is used: ## Subscribe to a merge request -Subscribes the authenticated user to a merge request to receive notification. If -the operation is successful, status code `201` together with the updated merge -request is returned. If the user is already subscribed to the merge request, the -status code `304` is returned. If the project or merge request is not found, -status code `404` is returned. +Subscribes the authenticated user to a merge request to receive notification. If the user is already subscribed to the merge request, the +status code `304` is returned. ``` POST /projects/:id/merge_requests/:merge_request_id/subscription @@ -747,10 +737,8 @@ Example response: ## Unsubscribe from a merge request Unsubscribes the authenticated user from a merge request to not receive -notifications from that merge request. If the operation is successful, status -code `200` together with the updated merge request is returned. If the user is -not subscribed to the merge request, the status code `304` is returned. If the -project or merge request is not found, status code `404` is returned. +notifications from that merge request. If the user is +not subscribed to the merge request, the status code `304` is returned. ``` DELETE /projects/:id/merge_requests/:merge_request_id/subscription @@ -822,9 +810,8 @@ Example response: ## Create a todo -Manually creates a todo for the current user on a merge request. If the -request is successful, status code `200` together with the created todo is -returned. If there already exists a todo for the user on that merge request, +Manually creates a todo for the current user on a merge request. +If there already exists a todo for the user on that merge request, status code `304` is returned. ``` @@ -1031,3 +1018,142 @@ Example response: }] } ``` +## Set a time estimate for a merge request + +Sets an estimated time of work for this merge request. + +``` +POST /projects/:id/merge_requests/:merge_request_id/time_estimate +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `merge_request_id` | integer | yes | The ID of a project's merge request | +| `duration` | string | yes | The duration in human format. e.g: 3h30m | + +```bash +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/merge_requests/93/time_estimate?duration=3h30m +``` + +Example response: + +```json +{ + "human_time_estimate": "3h 30m", + "human_total_time_spent": null, + "time_estimate": 12600, + "total_time_spent": 0 +} +``` + +## Reset the time estimate for a merge request + +Resets the estimated time for this merge request to 0 seconds. + +``` +POST /projects/:id/merge_requests/:merge_request_id/reset_time_estimate +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `merge_request_id` | integer | yes | The ID of a project's merge_request | + +```bash +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/merge_requests/93/reset_time_estimate +``` + +Example response: + +```json +{ + "human_time_estimate": null, + "human_total_time_spent": null, + "time_estimate": 0, + "total_time_spent": 0 +} +``` + +## Add spent time for a merge request + +Adds spent time for this merge request + +``` +POST /projects/:id/merge_requests/:merge_request_id/add_spent_time +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `merge_request_id` | integer | yes | The ID of a project's merge request | +| `duration` | string | yes | The duration in human format. e.g: 3h30m | + +```bash +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/merge_requests/93/add_spent_time?duration=1h +``` + +Example response: + +```json +{ + "human_time_estimate": null, + "human_total_time_spent": "1h", + "time_estimate": 0, + "total_time_spent": 3600 +} +``` + +## Reset spent time for a merge request + +Resets the total spent time for this merge request to 0 seconds. + +``` +POST /projects/:id/merge_requests/:merge_request_id/reset_spent_time +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `merge_request_id` | integer | yes | The ID of a project's merge_request | + +```bash +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/merge_requests/93/reset_spent_time +``` + +Example response: + +```json +{ + "human_time_estimate": null, + "human_total_time_spent": null, + "time_estimate": 0, + "total_time_spent": 0 +} +``` + +## Get time tracking stats + +``` +GET /projects/:id/merge_requests/:merge_request_id/time_stats +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `merge_request_id` | integer | yes | The ID of a project's merge request | + +```bash +curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/merge_requests/93/time_stats +``` + +Example response: + +```json +{ + "human_time_estimate": "2h", + "human_total_time_spent": "1h", + "time_estimate": 7200, + "total_time_spent": 3600 +} +``` |