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
Parameters:
| 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. |
| `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. |
......@@ -804,7 +804,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/participants
Parameters:
| 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. |
| `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
Parameters:
| 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. |
| `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
Parameters:
| 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. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `access_raw_diffs` | boolean | no | Retrieve change diffs via Gitaly. |
......@@ -1009,7 +1009,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/pipelines
Parameters:
| 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. |
| `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
Parameters:
| 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. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
......@@ -1446,7 +1446,7 @@ DELETE /projects/:id/merge_requests/:merge_request_iid
```
| 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. |
| `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
Parameters:
| 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. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `merge_commit_message` | string | no | Custom merge commit message. |
......@@ -1626,7 +1626,7 @@ 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. |
......@@ -1656,7 +1656,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/merge_ref
Parameters:
| 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. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
......@@ -1668,9 +1668,13 @@ Parameters:
## Cancel Merge When Pipeline Succeeds
- If you don't have permissions to accept this merge request - you receive a `HTTP 401 Unauthorized`.
- 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.
This API returns specific HTTP status codes on failure:
| 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
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_
Parameters:
| 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. |
| `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
```
| 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. |
| `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. |
......@@ -1909,7 +1913,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/closes_issues
```
| 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. |
| `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
```
| 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. |
| `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
```
| 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. |
| `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
```
| 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. |
| `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
```
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
|---------------------|---------|----------|---------------------------------------|
| `id` | String | yes | The ID of the project. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
......@@ -2486,9 +2490,11 @@ Example response:
### SHAs in the API response
- `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.
| SHA field | Purpose |
|--------------------|-------------------------------------------------------------------------------------|
| `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
......@@ -2500,7 +2506,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/versions/:version_id
```
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
|---------------------|---------|----------|-------------------------------------------|
| `id` | String | yes | The ID of the project. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `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
```
| 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. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `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
```
| 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. |
| `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
```
| 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. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `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
```
| 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. |
| `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
```
| 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. |
| `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