Add latest changes from gitlab-org/gitlab@15-6-stable-eev15.6.0-rc42

1 files changed, 104 insertions, 32 deletions

diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index 4667e48f233..4b4d36ec23e 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -160,6 +160,7 @@ Supported attributes:
     },
     "merge_when_pipeline_succeeds": true,
     "merge_status": "can_be_merged",
+    "detailed_merge_status": "not_open",
     "sha": "8888888888888888888888888888888888888888",
     "merge_commit_sha": null,
     "squash_commit_sha": null,
@@ -360,6 +361,7 @@ Supported attributes:
     },
     "merge_when_pipeline_succeeds": true,
     "merge_status": "can_be_merged",
+    "detailed_merge_status": "not_open",
     "sha": "8888888888888888888888888888888888888888",
     "merge_commit_sha": null,
     "squash_commit_sha": null,
@@ -547,6 +549,7 @@ Supported attributes:
     },
     "merge_when_pipeline_succeeds": true,
     "merge_status": "can_be_merged",
+    "detailed_merge_status": "not_open",
     "sha": "8888888888888888888888888888888888888888",
     "merge_commit_sha": null,
     "squash_commit_sha": null,
@@ -616,6 +619,67 @@ Supported attributes:
 | `include_rebase_in_progress`     | boolean        | **{dotted-circle}** No       | If `true`, response includes whether a rebase operation is in progress. |
 | `render_html`                    | boolean        | **{dotted-circle}** No       | If `true`, response includes rendered HTML for title and description. |
 
+### Response
+
+| Attribute                        | Type | Description |
+|----------------------------------|------|-------------|
+| `approvals_before_merge` | integer | **(PREMIUM)** Number of approvals required before this merge request can merge. |
+| `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. |
+| `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. |
+| `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. |
+| `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 will lead to source branch deletion after merge. |
+| `has_conflicts` | boolean | Indicates if merge request has conflicts and cannot be merged. 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. Contains more complete information than `pipeline` and should be used instead of it. |
+| `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 due to a merge error. |
+| `merge_user` | object | The user who merged this merge request, the user who set it to merge when pipeline succeeds, or `null`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/349031) in GitLab 14.7. |
+| `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. [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 has been set to be merged when its pipeline succeeds. |
+| `merged_at` | datetime | Timestamp of when the merge request was merged. |
+| `merged_by` | object | User who merged this merge request or set it to merge when pipeline succeeds. [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. |
+| `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 will 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 currently logged in user is subscribed 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. |
+
 ```json
 {
   "id": 155016530,
@@ -626,7 +690,7 @@ Supported attributes:
   "state": "opened",
   "created_at": "2022-05-13T07:26:38.402Z",
   "updated_at": "2022-05-14T03:38:31.354Z",
-  "merged_by": null, // Deprecated and will be removed in API v5, use `merge_user` instead
+  "merged_by": null, // Deprecated and will be removed in API v5. Use `merge_user` instead.
   "merge_user": null,
   "merged_at": null,
   "closed_by": null,
@@ -655,13 +719,14 @@ Supported attributes:
   "milestone": null,
   "merge_when_pipeline_succeeds": false,
   "merge_status": "can_be_merged",
+  "detailed_merge_status": "can_be_merged",
   "sha": "e82eb4a098e32c796079ca3915e07487fc4db24c",
   "merge_commit_sha": null,
   "squash_commit_sha": null,
   "discussion_locked": null,
   "should_remove_source_branch": null,
   "force_remove_source_branch": true,
-  "reference": "!133",
+  "reference": "!133", // Deprecated. Use `references` instead.
   "references": {
     "short": "!133",
     "relative": "!133",
@@ -687,7 +752,7 @@ Supported attributes:
   "latest_build_started_at": "2022-05-13T09:46:50.032Z",
   "latest_build_finished_at": null,
   "first_deployed_to_production_at": null,
-  "pipeline": { // Old parameter, use `head_pipeline` instead.
+  "pipeline": { // Use `head_pipeline` instead.
     "id": 538317940,
     "iid": 1877,
     "project_id": 15513260,
@@ -748,44 +813,43 @@ Supported attributes:
   "first_contribution": false,
   "user": {
     "can_merge": true
-  }
-}
-```
-
-Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see
-the `approvals_before_merge` parameter:
-
-```json
-{
-  "id": 1,
-  "title": "test1",
-  "approvals_before_merge": null
-  ...
+  },
+  "approvals_before_merge": { // Available for GitLab Premium and higher tiers only
+    "id": 1,
+    "title": "test1",
+    "approvals_before_merge": null
+  },
 }
 ```
 
 ### Single merge request response notes
 
-- The `merge_status` field may hold one of the following values:
-  - `unchecked`: This merge request has not yet been checked.
-  - `checking`: This merge request is currently being checked to see if it can be merged.
-  - `can_be_merged`: This merge request can be merged without conflict.
-  - `cannot_be_merged`: There are merge conflicts between the source and target branches.
-  - `cannot_be_merged_recheck`: Currently unchecked. Before the current changes, there were conflicts.
-- The `diff_refs` in the response correspond to the latest diff version of the merge request.
 - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29984) in GitLab 12.8, the mergeability (`merge_status`)
   of each merge request is checked asynchronously when a request is made to this endpoint. Poll this API endpoint
   to get updated status. This affects the `has_conflicts` property as it is dependent on the `merge_status`. It returns
   `false` unless `merge_status` is `cannot_be_merged`.
-- `references.relative` is relative to the group or project that the merge request is being requested. When the merge
-  request is fetched from its project, `relative` format would be the same as `short` format, and when requested across
-  groups or projects, it is expected to be the same as `full` format.
-- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/349031) in GitLab 14.7,
-  field `merge_user` can be either user who merged this merge request,
-  user who set it to merge when pipeline succeeds or `null`.
-  Field `merged_by` (user who merged this merge request or `null`) has been deprecated.
-- `pipeline` is an old parameter and should not be used. Use `head_pipeline` instead,
-  as it is faster and returns more information.
+
+### Merge status
+
+> - The `detailed_merge_status` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101724) in GitLab 15.6.
+> - The `merge_status` field was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/3169#note_1162532204) in GitLab 15.6.
+
+Use `detailed_merge_status` instead of `merge_status` to account for all potential statuses.
+
+- The `detailed_merge_status` field may hold one of the following values:
+  - `blocked_status`: Merge request is blocked by another merge request.
+  - `broken_status`: Can not merge the source into the target branch, potential conflict.
+  - `checking`: currently checking for mergeability.
+  - `ci_must_pass`: Pipeline must succeed before merging.
+  - `ci_still_running`: Pipeline is still running.
+  - `discussions_not_resolved`: Discussions must be resolved before merging.
+  - `draft_status`: Merge request must not be draft before merging.
+  - `external_status_checks`: Status checks must pass.
+  - `mergeable`: branch can be merged.
+  - `not_approved`: Merge request must be approved before merging.
+  - `not_open`: merge request must be open before merging.
+  - `policies_denied`: There are denied policies for the merge request.
+  - `unchecked`: merge status has not been checked.
 
 ## Get single MR participants
 
@@ -994,6 +1058,7 @@ Supported attributes:
   },
   "merge_when_pipeline_succeeds": true,
   "merge_status": "can_be_merged",
+  "detailed_merge_status": "can_be_merged",
   "subscribed" : true,
   "sha": "8888888888888888888888888888888888888888",
   "merge_commit_sha": null,
@@ -1211,6 +1276,7 @@ If `approvals_before_merge` is not provided, it inherits the value from the targ
   },
   "merge_when_pipeline_succeeds": true,
   "merge_status": "can_be_merged",
+  "detailed_merge_status": "not_open",
   "merge_error": null,
   "sha": "8888888888888888888888888888888888888888",
   "merge_commit_sha": null,
@@ -1392,6 +1458,7 @@ Must include at least one non-required attribute from above.
   },
   "merge_when_pipeline_succeeds": true,
   "merge_status": "can_be_merged",
+  "detailed_merge_status": "not_open",
   "merge_error": null,
   "sha": "8888888888888888888888888888888888888888",
   "merge_commit_sha": null,
@@ -1580,6 +1647,7 @@ Supported attributes:
   },
   "merge_when_pipeline_succeeds": true,
   "merge_status": "can_be_merged",
+  "detailed_merge_status": "not_open",
   "merge_error": null,
   "sha": "8888888888888888888888888888888888888888",
   "merge_commit_sha": null,
@@ -1792,6 +1860,7 @@ Supported attributes:
   },
   "merge_when_pipeline_succeeds": false,
   "merge_status": "can_be_merged",
+  "detailed_merge_status": "not_open",
   "merge_error": null,
   "sha": "8888888888888888888888888888888888888888",
   "merge_commit_sha": null,
@@ -2124,6 +2193,7 @@ Example response:
   },
   "merge_when_pipeline_succeeds": true,
   "merge_status": "can_be_merged",
+  "detailed_merge_status": "not_open",
   "sha": "8888888888888888888888888888888888888888",
   "merge_commit_sha": null,
   "squash_commit_sha": null,
@@ -2294,6 +2364,7 @@ Example response:
   },
   "merge_when_pipeline_succeeds": true,
   "merge_status": "can_be_merged",
+  "detailed_merge_status": "not_open",
   "sha": "8888888888888888888888888888888888888888",
   "merge_commit_sha": null,
   "squash_commit_sha": null,
@@ -2479,6 +2550,7 @@ Example response:
     },
     "merge_when_pipeline_succeeds": false,
     "merge_status": "unchecked",
+    "detailed_merge_status": "not_open",
     "subscribed": true,
     "sha": "8888888888888888888888888888888888888888",
     "merge_commit_sha": null,