diff options
Diffstat (limited to 'doc/api/merge_requests.md')
-rw-r--r-- | doc/api/merge_requests.md | 136 |
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, |