2019-09-30 21:07:59 +05:30
# Merge request approvals API **(STARTER)**
2019-09-04 21:01:54 +05:30
Configuration for approvals on all Merge Requests (MR) in the project. Must be authenticated for all endpoints.
## Project-level MR approvals
### Get Configuration
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/183) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6.
2019-09-04 21:01:54 +05:30
You can request information about a project's approval configuration using the
following endpoint:
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
GET /projects/:id/approvals
```
**Parameters:**
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ------------------- |
| `id` | integer | yes | The ID of a project |
```json
{
"approvals_before_merge": 2,
"reset_approvals_on_push": true,
2020-03-13 15:44:24 +05:30
"disable_overriding_approvers_per_merge_request": false,
"merge_requests_author_approval": true,
"merge_requests_disable_committers_approval": false,
"require_password_to_approve": true
2019-09-04 21:01:54 +05:30
}
```
### Change configuration
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/183) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6.
2019-09-04 21:01:54 +05:30
If you are allowed to, you can change approval configuration using the following
endpoint:
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
POST /projects/:id/approvals
```
**Parameters:**
2019-10-12 21:52:04 +05:30
| Attribute | Type | Required | Description |
| ------------------------------------------------ | ------- | -------- | --------------------------------------------------------------------------------------------------- |
| `id` | integer | yes | The ID of a project |
2019-12-04 20:38:33 +05:30
| `approvals_before_merge` | integer | no | How many approvals are required before an MR can be merged. Deprecated in 12.0 in favor of Approval Rules API. |
2019-10-12 21:52:04 +05:30
| `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 |
2020-03-13 15:44:24 +05:30
| `require_password_to_approve` | boolean | no | Require approver to enter a password in order to authenticate before adding the approval |
2019-09-04 21:01:54 +05:30
```json
{
2019-12-04 20:38:33 +05:30
"approvals_before_merge": 2,
"reset_approvals_on_push": true,
"disable_overriding_approvers_per_merge_request": false,
"merge_requests_author_approval": false,
2020-03-13 15:44:24 +05:30
"merge_requests_disable_committers_approval": false,
"require_password_to_approve": true
2019-12-04 20:38:33 +05:30
}
```
### Get project-level rules
2020-03-13 15:44:24 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3.
> - `protected_branches` property was [introduced](https://gitlab.com/gitlab-org/gitlab/issues/460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7.
2019-12-04 20:38:33 +05:30
You can request information about a project's approval rules using the following endpoint:
2020-04-08 14:13:33 +05:30
```plaintext
2019-12-04 20:38:33 +05:30
GET /projects/:id/approval_rules
```
**Parameters:**
| Attribute | Type | Required | Description |
|----------------------|---------|----------|-----------------------------------------------------------|
| `id` | integer | yes | The ID of a project |
```json
[
{
"id": 1,
"name": "security",
"rule_type": "regular",
"eligible_approvers": [
{
2019-09-04 21:01:54 +05:30
"id": 5,
2019-12-04 20:38:33 +05:30
"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"
2019-09-04 21:01:54 +05:30
}
2019-12-04 20:38:33 +05:30
],
"approvals_required": 3,
"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,
2019-09-04 21:01:54 +05:30
"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
}
2019-12-04 20:38:33 +05:30
],
2020-03-13 15:44:24 +05:30
"protected_branches": [
{
"id": 1,
"name": "master",
"push_access_levels": [
{
"access_level": 30,
"access_level_description": "Developers + Maintainers"
}
],
"merge_access_levels": [
{
"access_level": 30,
"access_level_description": "Developers + Maintainers"
}
],
"unprotect_access_levels": [
{
"access_level": 40,
"access_level_description": "Maintainers"
}
],
"code_owner_approval_required": "false"
}
],
2019-12-04 20:38:33 +05:30
"contains_hidden_groups": false
}
]
```
### Create project-level rule
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3.
2019-12-04 20:38:33 +05:30
You can create project approval rules using the following endpoint:
2020-04-08 14:13:33 +05:30
```plaintext
2019-12-04 20:38:33 +05:30
POST /projects/:id/approval_rules
```
**Parameters:**
2020-03-13 15:44:24 +05:30
| Attribute | Type | Required | Description |
|------------------------|---------|----------|------------------------------------------------------------------|
| `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 |
| `user_ids` | Array | no | The ids of users as approvers |
| `group_ids` | Array | no | The ids of groups as approvers |
| `protected_branch_ids` | Array | no | ** (PREMIUM)** The ids of protected branches to scope the rule by |
2019-12-04 20:38:33 +05:30
```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"
2019-09-04 21:01:54 +05:30
}
],
2019-12-04 20:38:33 +05:30
"approvals_required": 1,
"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
}
],
2020-03-13 15:44:24 +05:30
"protected_branches": [
{
"id": 1,
"name": "master",
"push_access_levels": [
{
"access_level": 30,
"access_level_description": "Developers + Maintainers"
}
],
"merge_access_levels": [
{
"access_level": 30,
"access_level_description": "Developers + Maintainers"
}
],
"unprotect_access_levels": [
{
"access_level": 40,
"access_level_description": "Maintainers"
}
],
"code_owner_approval_required": "false"
}
],
2019-12-04 20:38:33 +05:30
"contains_hidden_groups": false
2019-09-04 21:01:54 +05:30
}
```
2019-12-04 20:38:33 +05:30
### Update project-level rule
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3.
2019-12-04 20:38:33 +05:30
You can update project approval rules using the following endpoint:
2020-04-08 14:13:33 +05:30
```plaintext
2019-12-04 20:38:33 +05:30
PUT /projects/:id/approval_rules/:approval_rule_id
```
2020-04-22 19:07:51 +05:30
**Important:** Approvers and groups not in the `users` /`groups` parameters will be **removed**
2019-12-04 20:38:33 +05:30
**Parameters:**
2020-03-13 15:44:24 +05:30
| Attribute | Type | Required | Description |
|------------------------|---------|----------|------------------------------------------------------------------|
| `id` | integer | yes | The ID of a project |
| `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 |
| `user_ids` | Array | no | The ids of users as approvers |
| `group_ids` | Array | no | The ids of groups as approvers |
| `protected_branch_ids` | Array | no | ** (PREMIUM)** The ids of protected branches to scope the rule by |
2019-12-04 20:38:33 +05:30
```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,
"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
}
],
2020-03-13 15:44:24 +05:30
"protected_branches": [
{
"id": 1,
"name": "master",
"push_access_levels": [
{
"access_level": 30,
"access_level_description": "Developers + Maintainers"
}
],
"merge_access_levels": [
{
"access_level": 30,
"access_level_description": "Developers + Maintainers"
}
],
"unprotect_access_levels": [
{
"access_level": 40,
"access_level_description": "Maintainers"
}
],
"code_owner_approval_required": "false"
}
],
2019-12-04 20:38:33 +05:30
"contains_hidden_groups": false
}
```
### Delete project-level rule
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3.
2019-12-04 20:38:33 +05:30
You can delete project approval rules using the following endpoint:
2020-04-08 14:13:33 +05:30
```plaintext
2019-12-04 20:38:33 +05:30
DELETE /projects/:id/approval_rules/:approval_rule_id
```
**Parameters:**
| Attribute | Type | Required | Description |
|----------------------|---------|----------|-----------------------------------------------------------|
| `id` | integer | yes | The ID of a project |
| `approval_rule_id` | integer | yes | The ID of a approval rule
2019-09-04 21:01:54 +05:30
### Change allowed approvers
2019-12-04 20:38:33 +05:30
>**Note:** This API endpoint has been deprecated. Please use Approval Rule API instead.
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/183) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6.
2019-09-04 21:01:54 +05:30
If you are allowed to, you can change approvers and approver groups using
the following endpoint:
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
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,
2020-03-13 15:44:24 +05:30
"disable_overriding_approvers_per_merge_request": false,
"merge_requests_author_approval": true,
"merge_requests_disable_committers_approval": false,
"require_password_to_approve": true
2019-09-04 21:01:54 +05:30
}
```
## Merge Request-level MR approvals
Configuration for approvals on a specific Merge Request. Must be authenticated for all endpoints.
### Get Configuration
2020-03-13 15:44:24 +05:30
> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.9.
2019-09-04 21:01:54 +05:30
You can request information about a merge request's approval status using the
following endpoint:
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
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",
2019-09-30 21:07:59 +05:30
"web_url": "http://localhost:3000/root"
2019-09-04 21:01:54 +05:30
}
}
],
}
```
### Change approval configuration
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/183) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6.
2019-09-04 21:01:54 +05:30
If you are allowed to, you can change `approvals_required` using the following
endpoint:
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
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 |
2019-12-04 20:38:33 +05:30
| `approvals_required` | integer | yes | Approvals required before MR can be merged. Deprecated in 12.0 in favor of Approval Rules API. |
2019-09-04 21:01:54 +05:30
```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,
2019-12-04 20:38:33 +05:30
"approved_by": []
2019-09-04 21:01:54 +05:30
}
```
### Change allowed approvers for Merge Request
2019-12-04 20:38:33 +05:30
>**Note:** This API endpoint has been deprecated. Please use Approval Rule API instead.
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/183) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6.
2019-09-04 21:01:54 +05:30
If you are allowed to, you can change approvers and approver groups using
the following endpoint:
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
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",
2019-09-30 21:07:59 +05:30
"web_url": "http://localhost:3000/root"
2019-09-04 21:01:54 +05:30
}
}
],
"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
}
}
]
}
```
2019-12-04 20:38:33 +05:30
### Get the approval state of merge requests
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13712) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3.
You can request information about a merge request's approval state by using the following endpoint:
2020-04-08 14:13:33 +05:30
```plaintext
2019-12-04 20:38:33 +05:30
GET /projects/:id/merge_requests/:merge_request_iid/approval_state
```
The `approval_rules_overwritten` will be `true` if the merge request level rules
are created for the merge request. If there's none, it'll be `false` .
This includes additional information about the users who have already approved
(`approved_by`) and whether a rule is already approved (`approved`).
**Parameters:**
| Attribute | Type | Required | Description |
|----------------------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a project |
| `merge_request_iid` | integer | yes | The IID of MR |
```json
{
"approval_rules_overwritten": true,
"rules": [
{
"id": 1,
"name": "Ruby",
"rule_type": "regular",
"eligible_approvers": [
{
"id": 4,
"name": "John Doe",
"username": "jdoe",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/0?s=80& d=identicon",
"web_url": "http://localhost/jdoe"
}
],
"approvals_required": 2,
"users": [
{
"id": 4,
"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": [],
"contains_hidden_groups": false,
"approved_by": [
{
"id": 4,
"name": "John Doe",
"username": "jdoe",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/0?s=80& d=identicon",
"web_url": "http://localhost/jdoe"
}
],
"source_rule": null,
2020-04-22 19:07:51 +05:30
"approved": true,
"overridden": false
2019-12-04 20:38:33 +05:30
}
]
}
```
### Get merge request level rules
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13712) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3.
2019-12-04 20:38:33 +05:30
You can request information about a merge request's approval rules using the following endpoint:
2020-04-08 14:13:33 +05:30
```plaintext
2019-12-04 20:38:33 +05:30
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
}
],
2020-04-22 19:07:51 +05:30
"contains_hidden_groups": false,
"overridden": false
2019-12-04 20:38:33 +05:30
}
]
```
### Create merge request level rule
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3.
2019-12-04 20:38:33 +05:30
You can create merge request approval rules using the following endpoint:
2020-04-08 14:13:33 +05:30
```plaintext
2019-12-04 20:38:33 +05:30
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 |
| `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
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
}
],
2020-04-22 19:07:51 +05:30
"contains_hidden_groups": false,
"overridden": false
2019-12-04 20:38:33 +05:30
}
```
### Update merge request level rule
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3.
2019-12-04 20:38:33 +05:30
You can update merge request approval rules using the following endpoint:
2020-04-08 14:13:33 +05:30
```plaintext
2020-03-13 15:44:24 +05:30
PUT /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id
2019-12-04 20:38:33 +05:30
```
2020-04-22 19:07:51 +05:30
**Important:** Approvers and groups not in the `users` /`groups` parameters will be **removed**
2019-12-04 20:38:33 +05:30
**Important:** Updating a `report_approver` or `code_owner` rule is not allowed.
These are system generated rules.
**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 |
| `user_ids` | Array | no | The ids of users as approvers |
| `group_ids` | Array | 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
}
],
2020-04-22 19:07:51 +05:30
"contains_hidden_groups": false,
"overridden": false
2019-12-04 20:38:33 +05:30
}
```
### Delete merge request level rule
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3.
2019-12-04 20:38:33 +05:30
You can delete merge request approval rules using the following endpoint:
2020-04-08 14:13:33 +05:30
```plaintext
2019-12-04 20:38:33 +05:30
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 |
|---------------------|---------|----------|---------------------------|
| `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 |
2019-09-04 21:01:54 +05:30
## Approve Merge Request
2020-03-13 15:44:24 +05:30
> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.9.
2019-09-04 21:01:54 +05:30
If you are allowed to, you can approve a merge request using the following
endpoint:
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
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 |
2020-03-13 15:44:24 +05:30
| `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 ) is enabled in the project settings. |
2019-09-04 21:01:54 +05:30
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",
2019-09-30 21:07:59 +05:30
"web_url": "http://localhost:3000/root"
2019-09-04 21:01:54 +05:30
}
},
{
"user": {
"name": "Nico Cartwright",
"username": "ryley",
"id": 2,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/cf7ad14b34162a76d593e3affca2adca?s=80\u0026d=identicon",
2019-09-30 21:07:59 +05:30
"web_url": "http://localhost:3000/ryley"
2019-09-04 21:01:54 +05:30
}
}
],
}
```
## Unapprove Merge Request
2020-03-13 15:44:24 +05:30
>Introduced in [GitLab Starter ](https://about.gitlab.com/pricing/ ) 9.0.
2019-09-04 21:01:54 +05:30
If you did approve a merge request, you can unapprove it using the following
endpoint:
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
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 |
