kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity
gitlab-org--gitlab-foss/doc/api/merge_request_approvals.md
James Ramsay f2dc791337 Add committer approval API attribute 
Merge Requests Approvals can be restricted to prevent the merge
request author or merge request committers from self approving. The
author restriction is already available in the API, but the committer
restriction was not.
2019-08-06 13:49:58 -04:00

13 KiB
Raw Blame History

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 
{
  "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 from self approving merge requests; true means authors cannot self approve
merge_requests_disable_committers_approval boolean no Allow/Disallow committers from self approving merge requests 
{
  "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,
  "merge_requests_disable_committers_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 
{
  "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 
{
  "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/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 
{
  "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 
{
  "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/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 is enabled in the project settings.

The sha parameter works in the same way as when accepting a merge request: 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.

{
  "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"
      }
    }
  ],
  "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