From 615b73c739e7d9e98241ca7c8d10f465f581d27f Mon Sep 17 00:00:00 2001 From: Patrick Bajao Date: Thu, 22 Aug 2019 20:42:15 +0800 Subject: [PATCH 1/5] Doc: Add documentation about public MR-level API --- doc/api/merge_request_approvals.md | 258 +++++++++++++++++++++++++++++ 1 file changed, 258 insertions(+) diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index bf83bfd7e6a..e1aca97f3a7 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -605,3 +605,261 @@ POST /projects/:id/merge_requests/:merge_request_iid/unapprove |---------------------|---------|----------|---------------------| | `id` | integer | yes | The ID of a project | | `merge_request_iid` | integer | yes | The IID of MR | + +### Get merge request level rules + +>**Note:** This API endpoint is only available on 12.3 Starter and above. + +You can request information about a merge request's approval rules using the following endpoint: + +``` +GET /projects/:id/merge_requests/:merge_request_iid/approval_rules +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +|---------------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | +| `merge_request_iid` | integer | yes | The IID of MR | + +```json +[ + { + "id": 1, + "name": "security", + "rule_type": "regular", + "eligible_approvers": [ + { + "id": 5, + "name": "John Doe", + "username": "jdoe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/jdoe" + }, + { + "id": 50, + "name": "Group Member 1", + "username": "group_member_1", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/group_member_1" + } + ], + "approvals_required": 3, + "source_rule": null, + "users": [ + { + "id": 5, + "name": "John Doe", + "username": "jdoe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/jdoe" + } + ], + "groups": [ + { + "id": 5, + "name": "group1", + "path": "group1", + "description": "", + "visibility": "public", + "lfs_enabled": false, + "avatar_url": null, + "web_url": "http://localhost/groups/group1", + "request_access_enabled": false, + "full_name": "group1", + "full_path": "group1", + "parent_id": null, + "ldap_cn": null, + "ldap_access": null + } + ], + "contains_hidden_groups": false + } +] +``` + +### Create merge request level rule + +>**Note:** This API endpoint is only available on 12.3 Starter and above. + +You can create merge request approval rules using the following endpoint: + +``` +POST /projects/:id/merge_requests/:merge_request_iid/approval_rules +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +|----------------------------|---------|----------|------------------------------------------------| +| `id` | integer | yes | The ID of a project | +| `merge_request_iid` | integer | yes | The IID of MR | +| `name` | string | yes | The name of the approval rule | +| `approvals_required` | integer | yes | The number of required approvals for this rule | +| `approval_project_rule_id` | integer | no | The ID of a project-level approval rule | +| `users` | integer | no | The ids of users as approvers | +| `groups` | integer | no | The ids of groups as approvers | + +**Important:** WHen `approval_project_rule_id` is set, the `name`, `users` and +`groups` of project-level rule will be copied. The `approvals_required` specified +will be used. + +```json +{ + "id": 1, + "name": "security", + "rule_type": "regular", + "eligible_approvers": [ + { + "id": 2, + "name": "John Doe", + "username": "jdoe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/jdoe" + }, + { + "id": 50, + "name": "Group Member 1", + "username": "group_member_1", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/group_member_1" + } + ], + "approvals_required": 1, + "source_rule": null, + "users": [ + { + "id": 2, + "name": "John Doe", + "username": "jdoe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/jdoe" + } + ], + "groups": [ + { + "id": 5, + "name": "group1", + "path": "group1", + "description": "", + "visibility": "public", + "lfs_enabled": false, + "avatar_url": null, + "web_url": "http://localhost/groups/group1", + "request_access_enabled": false, + "full_name": "group1", + "full_path": "group1", + "parent_id": null, + "ldap_cn": null, + "ldap_access": null + } + ], + "contains_hidden_groups": false +} +``` + +### Update merge request level rule + +>**Note:** This API endpoint is only available on 12.3 Starter and above. + +You can update merge request approval rules using the following endpoint: + +``` +PUT /projects/:id/merge_request/:merge_request_iid/approval_rules/:approval_rule_id +``` + +**Important:** Approvers and groups not in the `users`/`groups` param will be **removed** + +**Parameters:** + +| Attribute | Type | Required | Description | +|----------------------|---------|----------|------------------------------------------------| +| `id` | integer | yes | The ID of a project | +| `merge_request_iid` | integer | yes | The ID of MR | +| `approval_rule_id` | integer | yes | The ID of a approval rule | +| `name` | string | yes | The name of the approval rule | +| `approvals_required` | integer | yes | The number of required approvals for this rule | +| `users` | integer | no | The ids of users as approvers | +| `groups` | integer | no | The ids of groups as approvers | + +```json +{ + "id": 1, + "name": "security", + "rule_type": "regular", + "eligible_approvers": [ + { + "id": 2, + "name": "John Doe", + "username": "jdoe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/jdoe" + }, + { + "id": 50, + "name": "Group Member 1", + "username": "group_member_1", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/group_member_1" + } + ], + "approvals_required": 1, + "source_rule": null, + "users": [ + { + "id": 2, + "name": "John Doe", + "username": "jdoe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/jdoe" + } + ], + "groups": [ + { + "id": 5, + "name": "group1", + "path": "group1", + "description": "", + "visibility": "public", + "lfs_enabled": false, + "avatar_url": null, + "web_url": "http://localhost/groups/group1", + "request_access_enabled": false, + "full_name": "group1", + "full_path": "group1", + "parent_id": null, + "ldap_cn": null, + "ldap_access": null + } + ], + "contains_hidden_groups": false +} +``` + +### Delete merge request level rule + +>**Note:** This API endpoint is only available on 12.3 Starter and above. + +You can delete merge request approval rules using the following endpoint: + +``` +DELETE /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +|---------------------|---------|----------|---------------------------| +| `id` | integer | yes | The ID of a project | +| `merge_request_iid` | integer | yes | The ID of MR | +| `approval_rule_id` | integer | yes | The ID of a approval rule | From efbc7a39da14634105596a964e530530f7178058 Mon Sep 17 00:00:00 2001 From: Patrick Bajao Date: Fri, 23 Aug 2019 15:50:41 +0800 Subject: [PATCH 2/5] Doc: Add info about update/delete restriction --- doc/api/merge_request_approvals.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index e1aca97f3a7..e60560d5625 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -704,7 +704,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approval_rules | `users` | integer | no | The ids of users as approvers | | `groups` | integer | no | The ids of groups as approvers | -**Important:** WHen `approval_project_rule_id` is set, the `name`, `users` and +**Important:** When `approval_project_rule_id` is set, the `name`, `users` and `groups` of project-level rule will be copied. The `approvals_required` specified will be used. @@ -777,6 +777,9 @@ PUT /projects/:id/merge_request/:merge_request_iid/approval_rules/:approval_rule **Important:** Approvers and groups not in the `users`/`groups` param will be **removed** +**Important:** Updating a `report_approver` or `code_owner` rule is not allowed. +These are system generated rules. + **Parameters:** | Attribute | Type | Required | Description | @@ -856,6 +859,9 @@ You can delete merge request approval rules using the following endpoint: DELETE /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id ``` +**Important:** Deleting a `report_approver` or `code_owner` rule is not allowed. +These are system generated rules. + **Parameters:** | Attribute | Type | Required | Description | From 32ec0b7ac9975244a7cfe0872cc76a9f7ae780ce Mon Sep 17 00:00:00 2001 From: Patrick Bajao Date: Wed, 28 Aug 2019 09:53:50 +0800 Subject: [PATCH 3/5] Doc: Fix type of users and groups params --- doc/api/merge_request_approvals.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index e60560d5625..84b623f1254 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -152,8 +152,8 @@ POST /projects/:id/approval_rules | `id` | integer | yes | The ID of a project | | `name` | string | yes | The name of the approval rule | | `approvals_required` | integer | yes | The number of required approvals for this rule | -| `users` | integer | no | The ids of users as approvers | -| `groups` | integer | no | The ids of groups as approvers | +| `users` | Array | no | The ids of users as approvers | +| `groups` | Array | no | The ids of groups as approvers | ```json { @@ -231,8 +231,8 @@ PUT /projects/:id/approval_rules/:approval_rule_id | `approval_rule_id` | integer | yes | The ID of a approval rule | | `name` | string | yes | The name of the approval rule | | `approvals_required` | integer | yes | The number of required approvals for this rule | -| `users` | integer | no | The ids of users as approvers | -| `groups` | integer | no | The ids of groups as approvers | +| `users` | Array | no | The ids of users as approvers | +| `groups` | Array | no | The ids of groups as approvers | ```json { @@ -701,8 +701,8 @@ POST /projects/:id/merge_requests/:merge_request_iid/approval_rules | `name` | string | yes | The name of the approval rule | | `approvals_required` | integer | yes | The number of required approvals for this rule | | `approval_project_rule_id` | integer | no | The ID of a project-level approval rule | -| `users` | integer | no | The ids of users as approvers | -| `groups` | integer | no | The ids of groups as approvers | +| `users` | Array | no | The ids of users as approvers | +| `groups` | Array | no | The ids of groups as approvers | **Important:** When `approval_project_rule_id` is set, the `name`, `users` and `groups` of project-level rule will be copied. The `approvals_required` specified @@ -789,8 +789,8 @@ These are system generated rules. | `approval_rule_id` | integer | yes | The ID of a approval rule | | `name` | string | yes | The name of the approval rule | | `approvals_required` | integer | yes | The number of required approvals for this rule | -| `users` | integer | no | The ids of users as approvers | -| `groups` | integer | no | The ids of groups as approvers | +| `users` | Array | no | The ids of users as approvers | +| `groups` | Array | no | The ids of groups as approvers | ```json { From 32900bbfc440b9948f8ac26c04f254b9619769d4 Mon Sep 17 00:00:00 2001 From: Patrick Bajao Date: Thu, 29 Aug 2019 10:30:49 +0800 Subject: [PATCH 4/5] Doc: Update POST/PUT endpoints to use *_ids params --- doc/api/merge_request_approvals.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index 84b623f1254..7dae1b25658 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -152,8 +152,8 @@ POST /projects/:id/approval_rules | `id` | integer | yes | The ID of a project | | `name` | string | yes | The name of the approval rule | | `approvals_required` | integer | yes | The number of required approvals for this rule | -| `users` | Array | no | The ids of users as approvers | -| `groups` | Array | no | The ids of groups as approvers | +| `user_ids` | Array | no | The ids of users as approvers | +| `group_ids` | Array | no | The ids of groups as approvers | ```json { @@ -231,8 +231,8 @@ PUT /projects/:id/approval_rules/:approval_rule_id | `approval_rule_id` | integer | yes | The ID of a approval rule | | `name` | string | yes | The name of the approval rule | | `approvals_required` | integer | yes | The number of required approvals for this rule | -| `users` | Array | no | The ids of users as approvers | -| `groups` | Array | no | The ids of groups as approvers | +| `user_ids` | Array | no | The ids of users as approvers | +| `group_ids` | Array | no | The ids of groups as approvers | ```json { @@ -701,8 +701,8 @@ POST /projects/:id/merge_requests/:merge_request_iid/approval_rules | `name` | string | yes | The name of the approval rule | | `approvals_required` | integer | yes | The number of required approvals for this rule | | `approval_project_rule_id` | integer | no | The ID of a project-level approval rule | -| `users` | Array | no | The ids of users as approvers | -| `groups` | Array | no | The ids of groups as approvers | +| `user_ids` | Array | no | The ids of users as approvers | +| `group_ids` | Array | no | The ids of groups as approvers | **Important:** When `approval_project_rule_id` is set, the `name`, `users` and `groups` of project-level rule will be copied. The `approvals_required` specified @@ -789,8 +789,8 @@ These are system generated rules. | `approval_rule_id` | integer | yes | The ID of a approval rule | | `name` | string | yes | The name of the approval rule | | `approvals_required` | integer | yes | The number of required approvals for this rule | -| `users` | Array | no | The ids of users as approvers | -| `groups` | Array | no | The ids of groups as approvers | +| `user_ids` | Array | no | The ids of users as approvers | +| `group_ids` | Array | no | The ids of groups as approvers | ```json { From 70be63f936b01f4ae2f5e7deaadbc51ac082d90c Mon Sep 17 00:00:00 2001 From: Patrick Bajao Date: Fri, 30 Aug 2019 14:35:13 +0800 Subject: [PATCH 5/5] Doc: Fix order of sections --- doc/api/merge_request_approvals.md | 162 ++++++++++++++--------------- 1 file changed, 81 insertions(+), 81 deletions(-) diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index 7dae1b25658..b73fe38f53e 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -525,87 +525,6 @@ PUT /projects/:id/merge_requests/:merge_request_iid/approvers } ``` -## Approve Merge Request - ->**Note:** This API endpoint is only available on 8.9 Starter and above. - -If you are allowed to, you can approve a merge request using the following -endpoint: - -``` -POST /projects/:id/merge_requests/:merge_request_iid/approve -``` - -**Parameters:** - -| Attribute | Type | Required | Description | -|---------------------|---------|----------|-------------------------| -| `id` | integer | yes | The ID of a project | -| `merge_request_iid` | integer | yes | The IID of MR | -| `sha` | string | no | The HEAD of the MR | -| `approval_password` **(STARTER)** | string | no | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/merge_request_approvals.md#require-authentication-when-approving-a-merge-request-starter) is enabled in the project settings. | - -The `sha` parameter works in the same way as -when [accepting a merge request](merge_requests.md#accept-mr): if it is passed, then it must -match the current HEAD of the merge request for the approval to be added. If it -does not match, the response code will be `409`. - -```json -{ - "id": 5, - "iid": 5, - "project_id": 1, - "title": "Approvals API", - "description": "Test", - "state": "opened", - "created_at": "2016-06-08T00:19:52.638Z", - "updated_at": "2016-06-09T21:32:14.105Z", - "merge_status": "can_be_merged", - "approvals_required": 2, - "approvals_left": 0, - "approved_by": [ - { - "user": { - "name": "Administrator", - "username": "root", - "id": 1, - "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", - "web_url": "http://localhost:3000/root" - } - }, - { - "user": { - "name": "Nico Cartwright", - "username": "ryley", - "id": 2, - "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/cf7ad14b34162a76d593e3affca2adca?s=80\u0026d=identicon", - "web_url": "http://localhost:3000/ryley" - } - } - ], -} -``` - -## Unapprove Merge Request - ->**Note:** This API endpoint is only available on 9.0 Starter and above. - -If you did approve a merge request, you can unapprove it using the following -endpoint: - -``` -POST /projects/:id/merge_requests/:merge_request_iid/unapprove -``` - -**Parameters:** - -| Attribute | Type | Required | Description | -|---------------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | -| `merge_request_iid` | integer | yes | The IID of MR | - ### Get merge request level rules >**Note:** This API endpoint is only available on 12.3 Starter and above. @@ -869,3 +788,84 @@ These are system generated rules. | `id` | integer | yes | The ID of a project | | `merge_request_iid` | integer | yes | The ID of MR | | `approval_rule_id` | integer | yes | The ID of a approval rule | + +## Approve Merge Request + +>**Note:** This API endpoint is only available on 8.9 Starter and above. + +If you are allowed to, you can approve a merge request using the following +endpoint: + +``` +POST /projects/:id/merge_requests/:merge_request_iid/approve +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +|---------------------|---------|----------|-------------------------| +| `id` | integer | yes | The ID of a project | +| `merge_request_iid` | integer | yes | The IID of MR | +| `sha` | string | no | The HEAD of the MR | +| `approval_password` **(STARTER)** | string | no | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/merge_request_approvals.md#require-authentication-when-approving-a-merge-request-starter) is enabled in the project settings. | + +The `sha` parameter works in the same way as +when [accepting a merge request](merge_requests.md#accept-mr): if it is passed, then it must +match the current HEAD of the merge request for the approval to be added. If it +does not match, the response code will be `409`. + +```json +{ + "id": 5, + "iid": 5, + "project_id": 1, + "title": "Approvals API", + "description": "Test", + "state": "opened", + "created_at": "2016-06-08T00:19:52.638Z", + "updated_at": "2016-06-09T21:32:14.105Z", + "merge_status": "can_be_merged", + "approvals_required": 2, + "approvals_left": 0, + "approved_by": [ + { + "user": { + "name": "Administrator", + "username": "root", + "id": 1, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", + "web_url": "http://localhost:3000/root" + } + }, + { + "user": { + "name": "Nico Cartwright", + "username": "ryley", + "id": 2, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/cf7ad14b34162a76d593e3affca2adca?s=80\u0026d=identicon", + "web_url": "http://localhost:3000/ryley" + } + } + ], +} +``` + +## Unapprove Merge Request + +>**Note:** This API endpoint is only available on 9.0 Starter and above. + +If you did approve a merge request, you can unapprove it using the following +endpoint: + +``` +POST /projects/:id/merge_requests/:merge_request_iid/unapprove +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +|---------------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | +| `merge_request_iid` | integer | yes | The IID of MR |