diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 9e1910466a09c935a75e3312d36b707352b6f104..0ee3aadd6ab42b942a7c939e63d71e68bbfe4d39 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -674,75 +674,46 @@ GET /projects/:id/merge_requests/:merge_request_iid Supported attributes: -| Attribute | Type | Required | Description | -|----------------------------------|----------------|----------|-------------| +| Attribute | Type | Required | Description | +|----------------------------------|-------------------|----------|-------------| | `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths). | -| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | -| `include_diverged_commits_count` | boolean | No | If `true`, response includes the commits behind the target branch. | -| `include_rebase_in_progress` | boolean | No | If `true`, response includes whether a rebase operation is in progress. | -| `render_html` | boolean | No | If `true`, response includes rendered HTML for title and description. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +| `include_diverged_commits_count` | boolean | No | If `true`, response includes the commits behind the target branch. | +| `include_rebase_in_progress` | boolean | No | If `true`, response includes whether a rebase operation is in progress. | +| `render_html` | boolean | No | If `true`, response includes rendered HTML for title and description. | + +If successful, returns [`200 OK`](rest/troubleshooting.md#status-codes) + +Other possible responses: + +- `401 Unauthorized` if authentication is required, but the user is not authenticated. +- `404 Not Found` if the project or merge request is not found. +- `403 Forbidden` if the user doesn't have permission to view the merge request. +- `408 Request Timeout` if the database query times out. ### Response -| Attribute | Type | Description | -|----------------------------------|------|-------------| -| `approvals_before_merge`| integer | Number of approvals required before this merge request can merge. To configure approval rules, see [Merge request approvals API](merge_request_approvals.md). [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/353097) in GitLab 16.0. Premium and Ultimate only. | -| `assignee` | object | First assignee of the merge request. | -| `assignees` | array | Assignees of the merge request. | -| `author` | object | User who created this merge request. | -| `blocking_discussions_resolved` | boolean | Indicates if all discussions are resolved only if all are required before merge request can be merged. | -| `changes_count` | string | Number of changes made on the merge request. Empty when the merge request is created, and populates asynchronously. A string, not an integer. When a merge request has too many changes to display and store, the value is capped at 1000 and returns the string `"1000+"`. See [Empty API Fields for new merge requests](#empty-api-fields-for-new-merge-requests).| -| `closed_at` | datetime | Timestamp of when the merge request was closed. | -| `closed_by` | object | User who closed this merge request. | -| `created_at` | datetime | Timestamp of when the merge request was created. | -| `description` | string | Description of the merge request. Contains Markdown rendered as HTML for caching. | -| `detailed_merge_status` | string | Detailed merge status of the merge request. See [merge status](#merge-status) for a list of potential values. | -| `diff_refs` | object | References of the base SHA, the head SHA, and the start SHA for this merge request. Corresponds to the latest diff version of the merge request. Empty when the merge request is created, and populates asynchronously. See [Empty API fields for new merge requests](#empty-api-fields-for-new-merge-requests). | -| `discussion_locked` | boolean | Indicates if comments on the merge request are locked to members only. | -| `downvotes` | integer | Number of downvotes for the merge request. | -| `draft` | boolean | Indicates if the merge request is a draft. | -| `first_contribution` | boolean | Indicates if the merge request is the first contribution of the author. | -| `first_deployed_to_production_at` | datetime | Timestamp of when the first deployment finished. | -| `force_remove_source_branch` | boolean | Indicates if the project settings lead to source branch deletion after merge. | -| `has_conflicts` | boolean | Indicates if merge request has conflicts and cannot merge. Dependent on the `merge_status` property. Returns `false` unless `merge_status` is `cannot_be_merged`. | -| `head_pipeline` | object | Pipeline running on the branch HEAD of the merge request. Use instead of `pipeline`, because it contains more complete information. | -| `id` | integer | ID of the merge request. | -| `iid` | integer | Internal ID of the merge request. | -| `labels` | array | Labels of the merge request. | -| `latest_build_finished_at` | datetime | Timestamp of when the latest build for the merge request finished. | -| `latest_build_started_at` | datetime | Timestamp of when the latest build for the merge request started. | -| `merge_commit_sha` | string | SHA of the merge request commit. Returns `null` until merged. | -| `merge_error` | string | Error message shown when a merge has failed. To check mergeability, use `detailed_merge_status` instead | -| `merge_user` | object | The user who merged this merge request, the user who set it to auto-merge, or `null`. | -| `merge_status` | string | Status of the merge request. Can be `unchecked`, `checking`, `can_be_merged`, `cannot_be_merged`, or `cannot_be_merged_recheck`. Affects the `has_conflicts` property. For important notes on response data, see [Single merge request response notes](#single-merge-request-response-notes). [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/3169#note_1162532204) in GitLab 15.6. Use `detailed_merge_status` instead. | -| `merge_when_pipeline_succeeds` | boolean | Indicates if the merge is set to merge when its pipeline succeeds. | -| `merged_at` | datetime | Timestamp of when the merge request merged. | -| `merged_by` | object | User who merged this merge request or set it to auto-merge. [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/350534) in GitLab 14.7, and scheduled for removal in [API version 5](https://gitlab.com/groups/gitlab-org/-/epics/8115). Use `merge_user` instead. | -| `milestone` | object | Milestone of the merge request. | -| `pipeline` | object | Pipeline running on the branch HEAD of the merge request. Consider using `head_pipeline` instead, as it contains more information. | -| `prepared_at` | datetime | Timestamp of when the merge request was prepared. This field populates one time, only after all the [preparation steps](#preparation-steps) complete, and is not updated if more changes are added. | -| `project_id` | integer | ID of the merge request project. | -| `reference` | string | Internal reference of the merge request. Returned in shortened format by default. [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) in GitLab 12.7, and scheduled for removal in [API version 5](https://gitlab.com/groups/gitlab-org/-/epics/8115). Use `references` instead. | -| `references` | object | Internal references of the merge request. Includes `short`, `relative`, and `full` references. `references.relative` is relative to the merge request's group or project. When fetched from the merge request's project, `relative` and `short` formats are identical. When requested across groups or projects, `relative` and `full` formats are identical.| -| `reviewers` | array | Reviewers of the merge request. | -| `sha` | string | Diff head SHA of the merge request. | -| `should_remove_source_branch` | boolean | Indicates if the source branch of the merge request should be deleted after merge. | -| `source_branch` | string | Source branch of the merge request. | -| `source_project_id` | integer | ID of the merge request source project. | -| `squash` | boolean | Indicates if squash on merge is enabled. | -| `squash_commit_sha` | string | SHA of the squash commit. Empty until merged. | -| `state` | string | State of the merge request. Can be `opened`, `closed`, `merged` or `locked`. | -| `subscribed` | boolean | Indicates if the current authenticated user subscribes to this merge request. | -| `target_branch` | string | Target branch of the merge request. | -| `target_project_id` | integer | ID of the merge request target project. | -| `task_completion_status` | object | Completion status of tasks. | -| `title` | string | Title of the merge request. | -| `updated_at` | datetime | Timestamp of when the merge request was updated. | -| `upvotes` | integer | Number of upvotes for the merge request. | -| `user` | object | Permissions of the user requested for the merge request. | -| `user_notes_count` | integer | User notes count of the merge request. | -| `web_url` | string | Web URL of the merge request. | -| `work_in_progress` | boolean | Deprecated: Use `draft` instead. Indicates if the merge request is a draft. | +If successful, returns the same response attributes as [List project merge requests](#list-project-merge-requests), +and these additional fields: + +| Attribute | Type | Description | +|-----------------------------------|----------|-------------| +| `changes_count` | string | Number of changes made on the merge request. Empty when the merge request is created, and populates asynchronously. A string, not an integer. When a merge request has too many changes to display and store, the value is capped at 1000 and returns the string `"1000+"`. See [Empty API Fields for new merge requests](#empty-api-fields-for-new-merge-requests). | +| `completed_count` | integer | Number of completed task list items. | +| `count` | integer | Number of task list items. | +| `diff_refs` | object | References of the base SHA, the head SHA, and the start SHA for this merge request. Corresponds to the latest diff version of the merge request. Empty when the merge request is created, and populates asynchronously. See [Empty API fields for new merge requests](#empty-api-fields-for-new-merge-requests). | +| `diverged_commits_count` | integer | If `include_diverged_commits_count` is set, the number of diverged commits. | +| `first_contribution` | boolean | If set and `include_first_contribution` is true, the author's first contribution | +| `first_deployed_to_production_at` | dateTime | If builds are available, timestamp of when the first deployment finished. | +| `head_pipeline` | object | Pipeline running on the branch HEAD of the merge request. Use instead of `pipeline`, because it contains more complete information. | +| `latest_build_finished_at` | dateTime | If builds are available, timestamp of when the latest build finished. | +| `latest_build_started_at` | dateTime | If builds are available, timestamp of when the latest build started. | +| `merge_error` | string | Error message shown when a merge has failed. To check mergeability, use `detailed_merge_status` instead. | +| `pipeline` | object | If builds are available, the pipeline running on the branch HEAD of the merge request. Consider using `head_pipeline` instead, as it contains more information. | +| `rebase_in_progress` | boolean | If `include_rebase_in_progress` is set, whether a rebase is in progress. | +| `reviewers` | array | Reviewers of the merge request. | +| `subscribed` | boolean | If set, the current authenticated user subscribes to notifications for this merge request. | +| `user` | object | Permissions of the user requested for the merge request. Contains `can_merge` boolean indicating if current user can merge. | Example response: