From 9becaa63ef7263f21301267f7fb5d22fbfe0c362 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Tue, 23 Sep 2025 16:04:05 -0700 Subject: [PATCH 1/2] Add response codes to single-MR subheading Start by adding the various response codes for this endpoint. --- doc/api/merge_requests.md | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 9e1910466a09c9..a2c8c6306d4d47 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -674,19 +674,30 @@ 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 +If successful, returns the following response attributes: + | 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. | +| `approvals_before_merge`| integer | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/353097) in GitLab 16.0. To configure approval rules, see [Merge request approvals API](merge_request_approvals.md) instead. | | `assignee` | object | First assignee of the merge request. | | `assignees` | array | Assignees of the merge request. | | `author` | object | User who created this merge request. | @@ -714,15 +725,15 @@ Supported attributes: | `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_status` | string | [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. | +| `merged_by` | object | [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. | +| `reference` | string | [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. | @@ -742,7 +753,7 @@ Supported attributes: | `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. | +| `work_in_progress` | boolean | Deprecated: Use `draft` instead. | Example response: -- GitLab From 680727d306004d0a3b47c8264bfb71bca9241da9 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Tue, 23 Sep 2025 16:48:09 -0700 Subject: [PATCH 2/2] Build a simpler response table This endpoint duplicates the fields from the main merge request endpoint, but adds a few fields. What if, instead, we only did that giant response table one time, and then listed just the _added_ parameters on each subsequent endpoint? It might reduce duplicated work. --- doc/api/merge_requests.md | 82 ++++++++++----------------------------- 1 file changed, 21 insertions(+), 61 deletions(-) diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index a2c8c6306d4d47..0ee3aadd6ab42b 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -693,67 +693,27 @@ Other possible responses: ### Response -If successful, returns the following response attributes: - -| Attribute | Type | Description | -|----------------------------------|------|-------------| -| `approvals_before_merge`| integer | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/353097) in GitLab 16.0. To configure approval rules, see [Merge request approvals API](merge_request_approvals.md) instead. | -| `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 | [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 | [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 | [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. | +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: -- GitLab