diff options
Diffstat (limited to 'doc/api/merge_requests.md')
| -rw-r--r-- | doc/api/merge_requests.md | 144 |
1 files changed, 80 insertions, 64 deletions
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 905ecd05d52..a54ea33aca8 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -13,41 +13,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w Every API call to merge requests must be authenticated. -**Important notes:** - -- [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`. -- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0, listing merge requests may -not proactively update `merge_status` (which also affects the `has_conflicts`), as this can be an expensive operation. -If you need the value of these fields from this endpoint, set the `with_merge_status_recheck` parameter to -`true` in the query. -- `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. -- If `approvals_before_merge` is not provided, it inherits the value from the target project. If provided, the following conditions must hold for it to take effect: - - - The target project's `approvals_before_merge` must be greater than zero. A - value of zero disables approvals for that project. - - The provided value of `approvals_before_merge` must be greater than the - target project's `approvals_before_merge`. - - This API returns `HTTP 201 Created` for a successful response. - -- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46190) in GitLab 13.6, -diffs associated with the set of changes have the same size limitations applied as other diffs -returned by the API or viewed via the UI. When these limits impact the results, the `overflow` -field contains a value of `true`. Diff data without these limits applied can be retrieved by -adding the `access_raw_diffs` parameter, accessing diffs not from the database but from Gitaly directly. -This approach is generally slower and more resource-intensive, but isn't subject to size limits -placed on database-backed diffs. [Limits inherent to Gitaly](../development/diffs.md#diff-limits) -still apply. - -- [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. - ## List merge requests Get all merge requests the authenticated user has access to. By @@ -78,7 +43,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------------- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`. | -| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`. | +| `order_by` | string | no | Return requests ordered by `created_at`, `title`, or `updated_at` fields. Default is `created_at`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.8.| | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc`. | | `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | @@ -241,6 +206,14 @@ the `approvals_before_merge` parameter: ] ``` +### Merge requests list response notes + +- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0, listing merge requests may + not proactively update `merge_status` (which also affects the `has_conflicts`), as this can be an expensive operation. + If you need the value of these fields from this endpoint, set the `with_merge_status_recheck` parameter to + `true` in the query. +- For notes on merge request object fields, read [Single merge request response notes](#single-merge-request-response-notes). + ## List project merge requests Get all merge requests for this project. @@ -273,7 +246,7 @@ Parameters: | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `iids[]` | integer array | no | Return the request having the given `iid`. | | `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`. | -| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`. | +| `order_by` | string | no | Return requests ordered by `created_at`, `title` or `updated_at` fields. Default is `created_at`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.8. | | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc`. | | `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | @@ -421,16 +394,6 @@ Parameters: ] ``` -The `merge_status` field may hold one of the following values: - -| Value | Interpretation | -|----------------------------|-----------------------------------------------------------------------| -| `unchecked` | We have not checked this yet | -| `checking` | We are currently checking if the merge request 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 | - Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: @@ -445,6 +408,8 @@ the `approvals_before_merge` parameter: ] ``` +For important notes on response data, read [Merge requests list response notes](#merge-requests-list-response-notes). + ## List group merge requests Get all merge requests for this group and its subgroups. @@ -468,7 +433,7 @@ Parameters: | ------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | | `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`. | -| `order_by` | string | no | Return merge requests ordered by `created_at` or `updated_at` fields. Default is `created_at`. | +| `order_by` | string | no | Return merge requests ordered by `created_at`, `title` or `updated_at` fields. Default is `created_at`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.8. | | `sort` | string | no | Return merge requests sorted in `asc` or `desc` order. Default is `desc`. | | `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | @@ -627,6 +592,8 @@ the `approvals_before_merge` parameter: ] ``` +For important notes on response data, read [Merge requests list response notes](#merge-requests-list-response-notes). + ## Get single MR Shows information about a single merge request. @@ -805,7 +772,26 @@ the `approvals_before_merge` parameter: } ``` -The `diff_refs` in the response correspond to the latest diff version of the merge request. +### Single merge request response notes + +- The `merge_status` field may hold one of the following values: + - `unchecked`: We have not checked this yet. + - `checking`: We are currently checking if the merge request 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. ## Get single MR participants @@ -885,6 +871,15 @@ Parameters: Shows information about the merge request including its files and changes. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46190) in GitLab 13.6, +diffs associated with the set of changes have the same size limitations applied as other diffs +returned by the API or viewed via the UI. When these limits impact the results, the `overflow` +field contains a value of `true`. Diff data without these limits applied can be retrieved by +adding the `access_raw_diffs` parameter, accessing diffs not from the database but from Gitaly directly. +This approach is generally slower and more resource-intensive, but isn't subject to size limits +placed on database-backed diffs. [Limits inherent to Gitaly](../development/diffs.md#diff-limits) +still apply. + ```plaintext GET /projects/:id/merge_requests/:merge_request_iid/changes ``` @@ -1040,8 +1035,8 @@ It requires `.gitlab-ci.yml` to be configured with `only: [merge_requests]` to c The new pipeline can be: - A detached merge request pipeline. -- A [pipeline for merged results](../ci/pipelines/pipelines_for_merged_results.md) - if the [project setting is enabled](../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results). **(PREMIUM)** +- A [merged results pipeline](../ci/pipelines/merged_results_pipelines.md) + if the [project setting is enabled](../ci/pipelines/merged_results_pipelines.md#enable-merged-results-pipelines). ```plaintext POST /projects/:id/merge_requests/:merge_request_iid/pipelines @@ -1116,9 +1111,17 @@ POST /projects/:id/merge_requests | `milestone_id` | integer | no | The global ID of a milestone. | | `remove_source_branch` | boolean | no | Flag indicating if a merge request should remove the source branch when merging. | | `allow_collaboration` | boolean | no | Allow commits from members who can merge to the target branch. | -| `allow_maintainer_to_push` | boolean | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/22665), see `allow_collaboration`. | +| `allow_maintainer_to_push` | boolean | no | Alias of `allow_collaboration`. | +| `approvals_before_merge` **(PREMIUM)** | integer | no | Number of approvals required before this can be merged (see below). | | `squash` | boolean | no | Squash commits into a single commit when merging. | +If `approvals_before_merge` is not provided, it inherits the value from the target project. If provided, the following conditions must hold for it to take effect: + +- The target project's `approvals_before_merge` must be greater than zero. A + value of zero disables approvals for that project. +- The provided value of `approvals_before_merge` must be greater than the + target project's `approvals_before_merge`. + ```json { "id": 1, @@ -1251,6 +1254,8 @@ the `approvals_before_merge` parameter: } ``` +For important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). + ## Update MR Updates an existing merge request. You can change the target branch, title, or even close the MR. @@ -1278,7 +1283,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid | `squash` | boolean | no | Squash commits into a single commit when merging. | | `discussion_locked` | boolean | no | Flag indicating if the merge request's discussion is locked. If the discussion is locked only project members can add, edit or resolve comments. | | `allow_collaboration` | boolean | no | Allow commits from members who can merge to the target branch. | -| `allow_maintainer_to_push` | boolean | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/22665), see `allow_collaboration`. | +| `allow_maintainer_to_push` | boolean | no | Alias of `allow_collaboration`. | Must include at least one non-required attribute from above. @@ -1430,6 +1435,8 @@ the `approvals_before_merge` parameter: } ``` +For important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). + ## Delete a merge request Only for administrators and project owners. Deletes the merge request in question. @@ -1447,17 +1454,9 @@ DELETE /projects/:id/merge_requests/:merge_request_iid curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/merge_requests/85" ``` -## Accept MR - -Merge changes submitted with MR using this API. - -If a merge request is unable to be accepted (such as Draft, Closed, Pipeline Pending Completion, or Failed while requiring Success) - you receive a `405` and the error message 'Method Not Allowed' - -If it has some conflicts and can not be merged - you receive a `406` and the error message 'Branch cannot be merged' - -If the `sha` parameter is passed and does not match the HEAD of the source - you receive a `409` and the error message 'SHA does not match HEAD of source branch' +## Merge a merge request -If you don't have permissions to accept this merge request - you receive a `401` +Accept and merge changes submitted with MR using this API. ```plaintext PUT /projects/:id/merge_requests/:merge_request_iid/merge @@ -1624,6 +1623,17 @@ the `approvals_before_merge` parameter: } ``` +This API returns specific HTTP status codes on failure: + +| HTTP Status | Message | Reason | +| :---: | ------- | ------ | +| `401` | `Unauthorized` | This user does not have permission to accept this merge request. | +| `405` | `Method Not Allowed` | The merge request cannot be accepted because it is `Draft`, `Closed`, `Pipeline Pending Completion`, or `Failed`. `Success` is required. | +| `406` | `Branch cannot be merged` | The branch has conflicts and cannot be merged. | +| `409` | `SHA does not match HEAD of source branch` | The provided `sha` parameter does not match the HEAD of the source. | + +For additional important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). + ## Merge to default merge ref path Merge the changes between the merge request source and target branches into `refs/merge-requests/:iid/merge` @@ -1821,6 +1831,8 @@ the `approvals_before_merge` parameter: } ``` +For important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). + ## Rebase a merge request Automatically rebase the `source_branch` of the merge request against its @@ -2130,6 +2142,8 @@ the `approvals_before_merge` parameter: } ``` +For important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). + ## Unsubscribe from a merge request Unsubscribes the authenticated user from a merge request to not receive @@ -2298,6 +2312,8 @@ the `approvals_before_merge` parameter: } ``` +For important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). + ## Create a to-do item Manually creates a to-do item for the current user on a merge request. @@ -2686,7 +2702,7 @@ Example response: ## Approvals -For approvals, see [Merge Request Approvals](merge_request_approvals.md) +For approvals, see [Merge request approvals](merge_request_approvals.md) ## List merge request state events |