Skip to content

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 be able to self approve 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
}

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/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 
{
  "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/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 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/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