Skip to content

G
gitlab-ce
Commit 5a000354 authored by Amy Qualls's avatar Amy Qualls
Browse files
Options

Merge branch 'mr-api-doc-change' into 'master' 

Cleaned and updated Merge Request API doc

See merge request gitlab-org/gitlab!81405
parents 18f2af35 6107b72b
Show whitespace changes
Inline Side-by-side
Showing with 115 additions and 109 deletions
doc/api/merge_requests.md
View file @ 5a000354
...@@ -610,7 +610,7 @@ GET /projects/:id/merge_requests/:merge_request_iid ...@@ -610,7 +610,7 @@ GET /projects/:id/merge_requests/:merge_request_iid
Parameters: Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| |----------------------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `render_html` | boolean | no | If `true` response includes rendered HTML for title and description. | | `render_html` | boolean | no | If `true` response includes rendered HTML for title and description. |
...@@ -804,7 +804,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/participants ...@@ -804,7 +804,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/participants
Parameters: Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
...@@ -840,7 +840,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/commits ...@@ -840,7 +840,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/commits
Parameters: Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
...@@ -887,7 +887,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/changes ...@@ -887,7 +887,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/changes
Parameters: Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `access_raw_diffs` | boolean | no | Retrieve change diffs via Gitaly. | | `access_raw_diffs` | boolean | no | Retrieve change diffs via Gitaly. |
...@@ -1009,7 +1009,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/pipelines ...@@ -1009,7 +1009,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/pipelines
Parameters: Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
...@@ -1045,7 +1045,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/pipelines ...@@ -1045,7 +1045,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/pipelines
Parameters: Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
...@@ -1446,7 +1446,7 @@ DELETE /projects/:id/merge_requests/:merge_request_iid ...@@ -1446,7 +1446,7 @@ DELETE /projects/:id/merge_requests/:merge_request_iid
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
...@@ -1465,7 +1465,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid/merge ...@@ -1465,7 +1465,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid/merge
Parameters: Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|--------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| |--------------------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `merge_commit_message` | string | no | Custom merge commit message. | | `merge_commit_message` | string | no | Custom merge commit message. |
...@@ -1626,7 +1626,7 @@ the `approvals_before_merge` parameter: ...@@ -1626,7 +1626,7 @@ the `approvals_before_merge` parameter:
This API returns specific HTTP status codes on failure: This API returns specific HTTP status codes on failure:
| HTTP Status | Message | Reason | | HTTP Status | Message | Reason |
| :---: | ------- | ------ | |:------------|--------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
| `401` | `Unauthorized` | This user does not have permission to accept this merge request. | | `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. | | `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. | | `406` | `Branch cannot be merged` | The branch has conflicts and cannot be merged. |
...@@ -1656,7 +1656,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/merge_ref ...@@ -1656,7 +1656,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/merge_ref
Parameters: Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|--------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
...@@ -1668,9 +1668,13 @@ Parameters: ...@@ -1668,9 +1668,13 @@ Parameters:
## Cancel Merge When Pipeline Succeeds ## Cancel Merge When Pipeline Succeeds
- If you don't have permissions to accept this merge request - you receive a `HTTP 401 Unauthorized`. This API returns specific HTTP status codes on failure:
- If the merge request is already merged or closed - you receive a `HTTP 405 Method Not Allowed` and the error message 'Method Not Allowed'.
- In case the merge request is not set to be merged when the pipeline succeeds, you also receive a `HTTP 406 Not Acceptable` error. | HTTP Status | Message | Reason |
|-------------|----------------------|-----------------------------------------------------------------------|
| `401` | `Unauthorized` | This user does not have permission to cancel this merge request. |
| `405` | `Method Not Allowed` | The merge request is already merged or closed. |
| `406` | `Not Acceptable` | The merge request is not set to be merged when the pipeline succeeds. |
```plaintext ```plaintext
POST /projects/:id/merge_requests/:merge_request_iid/cancel_merge_when_pipeline_succeeds POST /projects/:id/merge_requests/:merge_request_iid/cancel_merge_when_pipeline_succeeds
...@@ -1679,7 +1683,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/cancel_merge_when_pipeline_ ...@@ -1679,7 +1683,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/cancel_merge_when_pipeline_
Parameters: Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|--------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
...@@ -1846,7 +1850,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid/rebase ...@@ -1846,7 +1850,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid/rebase
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `skip_ci` | boolean | no | Set to `true` to skip creating a CI pipeline. | | `skip_ci` | boolean | no | Set to `true` to skip creating a CI pipeline. |
...@@ -1909,7 +1913,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/closes_issues ...@@ -1909,7 +1913,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/closes_issues
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
...@@ -1985,7 +1989,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/subscribe ...@@ -1985,7 +1989,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/subscribe
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
...@@ -2155,7 +2159,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/unsubscribe ...@@ -2155,7 +2159,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/unsubscribe
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
...@@ -2325,7 +2329,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/todo ...@@ -2325,7 +2329,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/todo
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
...@@ -2452,7 +2456,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/versions ...@@ -2452,7 +2456,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/versions
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- | |---------------------|---------|----------|---------------------------------------|
| `id` | String | yes | The ID of the project. | | `id` | String | yes | The ID of the project. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
...@@ -2486,9 +2490,11 @@ Example response: ...@@ -2486,9 +2490,11 @@ Example response:
### SHAs in the API response ### SHAs in the API response
- `head_commit_sha`: The HEAD commit of the source branch. | SHA field | Purpose |
- `base_commit_sha`: The merge-base commit SHA between the source branch and the target branches. |--------------------|-------------------------------------------------------------------------------------|
- `start_commit_sha`: The HEAD commit SHA of the target branch when this version of the diff was created. | `head_commit_sha` | The HEAD commit of the source branch. |
| `base_commit_sha` | The merge-base commit SHA between the source branch and the target branches. |
| `start_commit_sha` | The HEAD commit SHA of the target branch when this version of the diff was created. |
## Get a single MR diff version ## Get a single MR diff version
...@@ -2500,7 +2506,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/versions/:version_id ...@@ -2500,7 +2506,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/versions/:version_id
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- | |---------------------|---------|----------|-------------------------------------------|
| `id` | String | yes | The ID of the project. | | `id` | String | yes | The ID of the project. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `version_id` | integer | yes | The ID of the merge request diff version. | | `version_id` | integer | yes | The ID of the merge request diff version. |
...@@ -2568,7 +2574,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/time_estimate ...@@ -2568,7 +2574,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/time_estimate
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `duration` | string | yes | The duration in human format, such as `3h30m`. | | `duration` | string | yes | The duration in human format, such as `3h30m`. |
...@@ -2597,7 +2603,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_time_estimate ...@@ -2597,7 +2603,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_time_estimate
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of a project's merge_request. | | `merge_request_iid` | integer | yes | The internal ID of a project's merge_request. |
...@@ -2625,7 +2631,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/add_spent_time ...@@ -2625,7 +2631,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/add_spent_time
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `duration` | string | yes | The duration in human format, such as `3h30m` | | `duration` | string | yes | The duration in human format, such as `3h30m` |
...@@ -2655,7 +2661,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_spent_time ...@@ -2655,7 +2661,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_spent_time
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of a project's merge_request. | | `merge_request_iid` | integer | yes | The internal ID of a project's merge_request. |
...@@ -2681,7 +2687,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/time_stats ...@@ -2681,7 +2687,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/time_stats
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |---------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. |
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7