diff options
Diffstat (limited to 'doc/api/merge_request_approvals.md')
| -rw-r--r-- | doc/api/merge_request_approvals.md | 425 |
1 files changed, 425 insertions, 0 deletions
diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md new file mode 100644 index 00000000000..ddac81328b9 --- /dev/null +++ b/doc/api/merge_request_approvals.md @@ -0,0 +1,425 @@ +# Merge request approvals API **[STARTER]** + +Configuration for approvals on all Merge Requests (MR) in the project. Must be authenticated for all endpoints. + +## Project-level MR approvals + +### Get Configuration + +>**Note:** This API endpoint is only available on 10.6 Starter and above. + +You can request information about a project's approval configuration using the +following endpoint: + +``` +GET /projects/:id/approvals +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | ------------------- | +| `id` | integer | yes | The ID of a project | + +```json +{ + "approvers": [ + { + "user": { + "id": 5, + "name": "John Doe6", + "username": "user5", + "state":"active","avatar_url":"https://www.gravatar.com/avatar/4aea8cf834ed91844a2da4ff7ae6b491?s=80\u0026d=identicon","web_url":"http://localhost/user5" + } + } + ], + "approver_groups": [ + { + "group": { + "id": 1, + "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 + } + } + ], + "approvals_before_merge": 2, + "reset_approvals_on_push": true, + "disable_overriding_approvers_per_merge_request": false +} +``` + +### Change configuration + +>**Note:** This API endpoint is only available on 10.6 Starter and above. + +If you are allowed to, you can change approval configuration using the following +endpoint: + +``` +POST /projects/:id/approvals +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +| ------------------------------------------------ | ------- | -------- | ---------------------------------------------------------- | +| `id` | integer | yes | The ID of a project | +| `approvals_before_merge` | integer | no | How many approvals are required before an MR can be merged | +| `reset_approvals_on_push` | boolean | no | Reset approvals on a new push | +| `disable_overriding_approvers_per_merge_request` | boolean | no | Allow/Disallow overriding approvers per MR | +| `merge_requests_author_approval` | boolean | no | Allow/Disallow authors be able to self approve merge requests | + +```json +{ + "approvers": [ + { + "user": { + "id": 5, + "name": "John Doe6", + "username": "user5", + "state":"active","avatar_url":"https://www.gravatar.com/avatar/4aea8cf834ed91844a2da4ff7ae6b491?s=80\u0026d=identicon","web_url":"http://localhost/user5" + } + } + ], + "approver_groups": [ + { + "group": { + "id": 1, + "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 + } + } + ], + "approvals_before_merge": 2, + "reset_approvals_on_push": true, + "disable_overriding_approvers_per_merge_request": false, + "merge_requests_author_approval": false +} +``` + +### Change allowed approvers + +>**Note:** This API endpoint is only available on 10.6 Starter and above. + +If you are allowed to, you can change approvers and approver groups using +the following endpoint: + +``` +PUT /projects/:id/approvers +``` + +**Important:** Approvers and groups not in the request will be **removed** + +**Parameters:** + +| Attribute | Type | Required | Description | +| -------------------- | ------- | -------- | --------------------------------------------------- | +| `id` | integer | yes | The ID of a project | +| `approver_ids` | Array | yes | An array of User IDs that can approve MRs | +| `approver_group_ids` | Array | yes | An array of Group IDs whose members can approve MRs | + +```json +{ + "approvers": [ + { + "user": { + "id": 5, + "name": "John Doe6", + "username": "user5", + "state":"active","avatar_url":"https://www.gravatar.com/avatar/4aea8cf834ed91844a2da4ff7ae6b491?s=80\u0026d=identicon","web_url":"http://localhost/user5" + } + } + ], + "approver_groups": [ + { + "group": { + "id": 1, + "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 + } + } + ], + "approvals_before_merge": 2, + "reset_approvals_on_push": true, + "disable_overriding_approvers_per_merge_request": false +} +``` + + +## Merge Request-level MR approvals + +Configuration for approvals on a specific Merge Request. Must be authenticated for all endpoints. + +### Get Configuration + +>**Note:** This API endpoint is only available on 8.9 Starter and above. + +You can request information about a merge request's approval status using the +following endpoint: + +``` +GET /projects/:id/merge_requests/:merge_request_iid/approvals +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +|---------------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | +| `merge_request_iid` | integer | yes | The IID of MR | + +```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-08T21:20:42.470Z", + "merge_status": "cannot_be_merged", + "approvals_required": 2, + "approvals_left": 1, + "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/u/root" + } + } + ], + "approvers": [], + "approver_groups": [] +} +``` + +### Change approval configuration + +>**Note:** This API endpoint is only available on 10.6 Starter and above. + +If you are allowed to, you can change `approvals_required` using the following +endpoint: + +``` +POST /projects/:id/merge_requests/:merge_request_iid/approvals +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +|----------------------|---------|----------|--------------------------------------------| +| `id` | integer | yes | The ID of a project | +| `merge_request_iid` | integer | yes | The IID of MR | +| `approvals_required` | integer | yes | Approvals required before MR can be merged | + + +```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-08T21:20:42.470Z", + "merge_status": "cannot_be_merged", + "approvals_required": 2, + "approvals_left": 2, + "approved_by": [], + "approvers": [], + "approver_groups": [] +} +``` + +### Change allowed approvers for Merge Request + +>**Note:** This API endpoint is only available on 10.6 Starter and above. + +If you are allowed to, you can change approvers and approver groups using +the following endpoint: + +``` +PUT /projects/:id/merge_requests/:merge_request_iid/approvers +``` + +**Important:** Approvers and groups not in the request will be **removed** + +**Parameters:** + +| Attribute | Type | Required | Description | +|----------------------|---------|----------|-----------------------------------------------------------| +| `id` | integer | yes | The ID of a project | +| `merge_request_iid` | integer | yes | The IID of MR | +| `approver_ids` | Array | yes | An array of User IDs that can approve the MR | +| `approver_group_ids` | Array | yes | An array of Group IDs whose members can approve the MR | + +```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-08T21:20:42.470Z", + "merge_status": "cannot_be_merged", + "approvals_required": 2, + "approvals_left": 2, + "approved_by": [], + "approvers": [ + { + "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/u/root" + } + } + ], + "approver_groups": [ + { + "group": { + "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 + } + } + ] +} +``` + +## 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/u/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/u/ryley" + } + } + ], + "approvers": [], + "approver_groups": [] +} +``` + +## 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 | |