2020-10-24 23:57:45 +05:30
---
stage: Create
group: Source Code
2022-11-25 23:54:43 +05:30
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments"
2020-10-24 23:57:45 +05:30
---
2021-03-11 19:13:27 +05:30
# Merge request approvals API **(PREMIUM)**
2019-09-04 21:01:54 +05:30
2023-07-09 08:55:56 +05:30
> - Changing approval configuration with the `/approvals` endpoint was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/11132) in GitLab 12.3.
> - Endpoint `/approvals` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/353097) in GitLab 16.0.
2023-01-13 00:05:48 +05:30
2021-04-29 21:17:54 +05:30
Configuration for
2021-06-08 01:23:25 +05:30
[approvals on all merge requests ](../user/project/merge_requests/approvals/index.md )
2021-04-29 21:17:54 +05:30
in the project. Must be authenticated for all endpoints.
2019-09-04 21:01:54 +05:30
## Project-level MR approvals
### Get Configuration
2023-03-17 16:20:25 +05:30
> - Moved to GitLab Premium in 13.9.
> - The `approvers` and `approver_groups` fields were deprecated in GitLab 12.3 and always return empty. Use the [project level approval rules](#get-project-level-rules) to access this information.
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
```
2022-10-11 01:57:18 +05:30
Supported attributes:
2019-09-04 21:01:54 +05:30
2023-03-17 16:20:25 +05:30
| Attribute | Type | Required | Description |
|-----------|-------------------|------------------------|-------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer or string | ** {check-circle}** Yes | The ID or [URL-encoded path of a project ](rest/index.md#namespaced-path-encoding ). |
2019-09-04 21:01:54 +05:30
```json
{
2023-03-17 16:20:25 +05:30
"approvers": [], // Deprecated in GitLab 12.3, always returns empty
"approver_groups": [], // Deprecated in GitLab 12.3, always returns empty
2019-09-04 21:01:54 +05:30
"approvals_before_merge": 2,
"reset_approvals_on_push": true,
2022-10-11 01:57:18 +05:30
"selective_code_owner_removals": false,
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
2021-11-18 22:05:49 +05:30
> Moved to GitLab Premium in 13.9.
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
```
2022-10-11 01:57:18 +05:30
Supported attributes:
2019-09-04 21:01:54 +05:30
2023-03-17 16:20:25 +05:30
| Attribute | Type | Required | Description |
|--------------------------------------------------|-------------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer or string | ** {check-circle}** Yes | The ID or [URL-encoded path of a project ](rest/index.md#namespaced-path-encoding ). |
2023-03-17 16:20:25 +05:30
| `approvals_before_merge` (deprecated) | integer | ** {dotted-circle}** No | How many approvals are required before a merge request can be merged. [Deprecated ](https://gitlab.com/gitlab-org/gitlab/-/issues/11132 ) in GitLab 12.3. |
| `disable_overriding_approvers_per_merge_request` | boolean | ** {dotted-circle}** No | Allow or prevent overriding approvers per merge request. |
| `merge_requests_author_approval` | boolean | ** {dotted-circle}** No | Allow or prevent authors from self approving merge requests; `true` means authors can self approve. |
| `merge_requests_disable_committers_approval` | boolean | ** {dotted-circle}** No | Allow or prevent committers from self approving merge requests. |
| `require_password_to_approve` | boolean | ** {dotted-circle}** No | Require approver to enter a password to authenticate before adding the approval. |
| `reset_approvals_on_push` | boolean | ** {dotted-circle}** No | Reset approvals on a new push. |
| `selective_code_owner_removals` | boolean | ** {dotted-circle}** No | Reset approvals from Code Owners if their files changed. Can be enabled only if `reset_approvals_on_push` is disabled. |
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,
2022-10-11 01:57:18 +05:30
"selective_code_owner_removals": false,
2019-12-04 20:38:33 +05:30
"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
2021-03-11 19:13:27 +05:30
> - Moved to GitLab Premium in 13.9.
2022-08-27 11:52:29 +05:30
> - Pagination support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31011) in GitLab 15.3 [with a flag](../administration/feature_flags.md) named `approval_rules_pagination`. Enabled by default.
> - `applies_to_all_protected_branches` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3.
2023-03-04 22:38:38 +05:30
> - Pagination support [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366823) in GitLab 15.7. Feature flag `approval_rules_pagination` removed.
> - `usernames` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in GitLab 15.8.
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
```
2023-04-23 21:23:45 +05:30
Use the `page` and `per_page` [pagination ](rest/index.md#offset-based-pagination ) parameters to restrict the list of approval rules.
2022-08-27 11:52:29 +05:30
2022-10-11 01:57:18 +05:30
Supported attributes:
2019-12-04 20:38:33 +05:30
2023-03-17 16:20:25 +05:30
| Attribute | Type | Required | Description |
|-----------|-------------------|------------------------|-------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer or string | ** {check-circle}** Yes | The ID or [URL-encoded path of a project ](rest/index.md#namespaced-path-encoding ). |
2019-12-04 20:38:33 +05:30
```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
],
2022-08-27 11:52:29 +05:30
"applies_to_all_protected_branches": false,
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
}
]
```
2021-02-22 17:27:13 +05:30
### Get a single project-level rule
2022-08-27 11:52:29 +05:30
> - Introduced in GitLab 13.7.
> - `applies_to_all_protected_branches` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3.
2023-03-04 22:38:38 +05:30
> - `usernames` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in GitLab 1x.x.
2021-02-22 17:27:13 +05:30
You can request information about a single project approval rules using the following endpoint:
```plaintext
GET /projects/:id/approval_rules/:approval_rule_id
```
2022-10-11 01:57:18 +05:30
Supported attributes:
2021-02-22 17:27:13 +05:30
2023-03-17 16:20:25 +05:30
| Attribute | Type | Required | Description |
|--------------------|-------------------|------------------------|-------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer or string | ** {check-circle}** Yes | The ID or [URL-encoded path of a project ](rest/index.md#namespaced-path-encoding ). |
2023-03-17 16:20:25 +05:30
| `approval_rule_id` | integer | ** {check-circle}** Yes | The ID of a approval rule. |
2021-02-22 17:27:13 +05:30
```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,
"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
}
],
2022-08-27 11:52:29 +05:30
"applies_to_all_protected_branches": false,
2021-02-22 17:27:13 +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"
}
],
"contains_hidden_groups": false
}
```
2019-12-04 20:38:33 +05:30
### Create project-level rule
2021-03-11 19:13:27 +05:30
> - Moved to GitLab Premium in 13.9.
2022-07-16 23:28:13 +05:30
> - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357300) the Vulnerability-Check feature in GitLab 15.0.
2022-08-27 11:52:29 +05:30
> - `applies_to_all_protected_branches` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3.
2023-03-04 22:38:38 +05:30
> - `usernames` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in GitLab 1x.x.
2022-04-04 11:22:00 +05:30
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
```
2022-10-11 01:57:18 +05:30
Supported attributes:
2019-12-04 20:38:33 +05:30
2023-03-17 16:20:25 +05:30
| Attribute | Type | Required | Description |
|-------------------------------------|-------------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer or string | ** {check-circle}** Yes | The ID or [URL-encoded path of a project ](rest/index.md#namespaced-path-encoding ). |
2023-03-17 16:20:25 +05:30
| `approvals_required` | integer | ** {check-circle}** Yes | The number of required approvals for this rule. |
| `name` | string | ** {check-circle}** Yes | The name of the approval rule. |
| `applies_to_all_protected_branches` | boolean | ** {dotted-circle}** No | Whether the rule is applied to all protected branches. If set to `true` , the value of `protected_branch_ids` is ignored. Default is `false` . [Introduced ](https://gitlab.com/gitlab-org/gitlab/-/issues/335316 ) in GitLab 15.3. |
| `group_ids` | Array | ** {dotted-circle}** No | The IDs of groups as approvers. |
| `protected_branch_ids` | Array | ** {dotted-circle}** No | The IDs of protected branches to scope the rule by. To identify the ID, [use the API ](protected_branches.md#list-protected-branches ). |
2023-05-27 22:25:52 +05:30
| `report_type` | string | ** {dotted-circle}** No | The report type required when the rule type is `report_approver` . The supported report types are `license_scanning` [(Deprecated in GitLab 15.9) ](../update/deprecations.md#license-check-and-the-policies-tab-on-the-license-compliance-page ) and `code_coverage` . |
2023-03-17 16:20:25 +05:30
| `rule_type` | string | ** {dotted-circle}** No | The type of rule. `any_approver` is a pre-configured default rule with `approvals_required` at `0` . Other rules are `regular` . |
| `user_ids` | Array | ** {dotted-circle}** No | The IDs of users as approvers. |
| `usernames` | string array | ** {dotted-circle}** No | The usernames for this rule. |
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
}
],
2022-08-27 11:52:29 +05:30
"applies_to_all_protected_branches": false,
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
}
```
2021-11-18 22:05:49 +05:30
You can increase the default number of 0 required approvers like this:
```shell
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " \
--header 'Content-Type: application/json' \
--data '{"name": "Any name", "rule_type": "any_approver", "approvals_required": 2}'
```
Another example is creating an additional, user-specific rule:
```shell
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " \
--header 'Content-Type: application/json' \
--data '{"name": "Name of your rule", "approvals_required": 3, "user_ids": [123, 456, 789]}' \
https://gitlab.example.com/api/v4/projects/< project_id > /approval_rules
```
2019-12-04 20:38:33 +05:30
### Update project-level rule
2021-03-11 19:13:27 +05:30
> - Moved to GitLab Premium in 13.9.
2022-07-16 23:28:13 +05:30
> - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357300) the Vulnerability-Check feature in GitLab 15.0.
2022-08-27 11:52:29 +05:30
> - `applies_to_all_protected_branches` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3.
2023-03-04 22:38:38 +05:30
> - `usernames` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in GitLab 1x.x.
2022-04-04 11:22:00 +05:30
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
```
2021-04-17 20:07:23 +05:30
**Important:** Approvers and groups not in the `users` /`groups` parameters are **removed**
2019-12-04 20:38:33 +05:30
2022-10-11 01:57:18 +05:30
Supported attributes:
2019-12-04 20:38:33 +05:30
2023-03-17 16:20:25 +05:30
| Attribute | Type | Required | Description |
|-------------------------------------|-------------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer or string | ** {check-circle}** Yes | The ID or [URL-encoded path of a project ](rest/index.md#namespaced-path-encoding ). |
2023-03-17 16:20:25 +05:30
| `approvals_required` | integer | ** {check-circle}** Yes | The number of required approvals for this rule. |
| `approval_rule_id` | integer | ** {check-circle}** Yes | The ID of a approval rule. |
| `name` | string | ** {check-circle}** Yes | The name of the approval rule. |
| `applies_to_all_protected_branches` | boolean | ** {dotted-circle}** No | Whether the rule is applied to all protected branches. If set to `true` , the value of `protected_branch_ids` is ignored. Default is `false` . [Introduced ](https://gitlab.com/gitlab-org/gitlab/-/issues/335316 ) in GitLab 15.3. |
| `group_ids` | Array | ** {dotted-circle}** No | The IDs of groups as approvers. |
| `protected_branch_ids` | Array | ** {dotted-circle}** No | The IDs of protected branches to scope the rule by. To identify the ID, [use the API ](protected_branches.md#list-protected-branches ). |
| `remove_hidden_groups` | boolean | ** {dotted-circle}** No | Whether hidden groups should be removed. |
| `user_ids` | Array | ** {dotted-circle}** No | The IDs of users as approvers. |
| `usernames` | string array | ** {dotted-circle}** No | The usernames for this rule. |
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
}
],
2022-08-27 11:52:29 +05:30
"applies_to_all_protected_branches": false,
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
2022-10-11 01:57:18 +05:30
> Moved to GitLab Premium in 13.9.
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
```
2022-10-11 01:57:18 +05:30
Supported attributes:
2019-12-04 20:38:33 +05:30
2023-03-17 16:20:25 +05:30
| Attribute | Type | Required | Description |
|--------------------|-------------------|------------------------|-------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer or string | ** {check-circle}** Yes | The ID or [URL-encoded path of a project ](rest/index.md#namespaced-path-encoding ). |
2023-03-17 16:20:25 +05:30
| `approval_rule_id` | integer | ** {check-circle}** Yes | The ID of a approval rule. |
2019-12-04 20:38:33 +05:30
2022-04-04 11:22:00 +05:30
## Merge request-level MR approvals
2019-09-04 21:01:54 +05:30
2022-04-04 11:22:00 +05:30
Configuration for approvals on a specific merge request. Must be authenticated for all endpoints.
2019-09-04 21:01:54 +05:30
### Get Configuration
2021-11-18 22:05:49 +05:30
> Moved to GitLab Premium in 13.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
```
2022-10-11 01:57:18 +05:30
Supported attributes:
2019-09-04 21:01:54 +05:30
2023-03-17 16:20:25 +05:30
| Attribute | Type | Required | Description |
|---------------------|-------------------|------------------------|-------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer or string | ** {check-circle}** Yes | The ID or [URL-encoded path of a project ](rest/index.md#namespaced-path-encoding ). |
2023-03-17 16:20:25 +05:30
| `merge_request_iid` | integer | ** {check-circle}** Yes | The IID of the merge request. |
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": 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
}
}
2021-06-08 01:23:25 +05:30
]
2019-09-04 21:01:54 +05:30
}
```
2019-12-04 20:38:33 +05:30
### Get the approval state of merge requests
2022-10-11 01:57:18 +05:30
> Moved to GitLab Premium in 13.9.
2019-12-04 20:38:33 +05:30
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
```
2021-04-17 20:07:23 +05:30
The `approval_rules_overwritten` are `true` if the merge request level rules
are created for the merge request. If there are none, it is `false` .
2019-12-04 20:38:33 +05:30
This includes additional information about the users who have already approved
(`approved_by`) and whether a rule is already approved (`approved`).
2022-10-11 01:57:18 +05:30
Supported attributes:
2019-12-04 20:38:33 +05:30
2023-03-17 16:20:25 +05:30
| Attribute | Type | Required | Description |
|---------------------|-------------------|------------------------|-------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer or string | ** {check-circle}** Yes | The ID or [URL-encoded path of a project ](rest/index.md#namespaced-path-encoding ). |
2023-03-17 16:20:25 +05:30
| `merge_request_iid` | integer | ** {check-circle}** Yes | The IID of the merge request. |
2019-12-04 20:38:33 +05:30
```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
2021-03-11 19:13:27 +05:30
> - Moved to GitLab Premium in 13.9.
2022-08-27 11:52:29 +05:30
> - Pagination support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31011) in GitLab 15.3 [with a flag](../administration/feature_flags.md) named `approval_rules_pagination`. Enabled by default.
2023-03-04 22:38:38 +05:30
> - Pagination support [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366823) in GitLab 15.7. Feature flag `approval_rules_pagination` removed.
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
```
2023-04-23 21:23:45 +05:30
Use the `page` and `per_page` [pagination ](rest/index.md#offset-based-pagination ) parameters to restrict the list of approval rules.
2022-08-27 11:52:29 +05:30
2022-10-11 01:57:18 +05:30
Supported attributes:
2019-12-04 20:38:33 +05:30
2023-03-17 16:20:25 +05:30
| Attribute | Type | Required | Description |
|---------------------|-------------------|------------------------|-------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer or string | ** {check-circle}** Yes | The ID or [URL-encoded path of a project ](rest/index.md#namespaced-path-encoding ). |
2023-03-17 16:20:25 +05:30
| `merge_request_iid` | integer | ** {check-circle}** Yes | The IID of the merge request. |
2019-12-04 20:38:33 +05:30
```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
}
]
```
2022-06-21 17:19:12 +05:30
### Get a single merge request level rule
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82767) in GitLab 14.10.
You can request information about a single merge request approval rule using the following endpoint:
```plaintext
GET /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id
```
2022-10-11 01:57:18 +05:30
Supported attributes:
2022-06-21 17:19:12 +05:30
2023-03-17 16:20:25 +05:30
| Attribute | Type | Required | Description |
|---------------------|-------------------|------------------------|-------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer or string | ** {check-circle}** Yes | The ID or [URL-encoded path of a project ](rest/index.md#namespaced-path-encoding ). |
2023-03-17 16:20:25 +05:30
| `approval_rule_id` | integer | ** {check-circle}** Yes | The ID of an approval rule. |
| `merge_request_iid` | integer | ** {check-circle}** Yes | The IID of a merge request. |
2022-06-21 17:19:12 +05:30
```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,
"overridden": false
}
```
2019-12-04 20:38:33 +05:30
### Create merge request level rule
2022-10-11 01:57:18 +05:30
> Moved to GitLab Premium in 13.9.
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
```
2022-10-11 01:57:18 +05:30
Supported attributes:
2019-12-04 20:38:33 +05:30
2023-03-17 16:20:25 +05:30
| Attribute | Type | Required | Description |
|----------------------------|-------------------|------------------------|------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer or string | ** {check-circle}** Yes | The ID or [URL-encoded path of a project ](rest/index.md#namespaced-path-encoding ) |
2023-03-17 16:20:25 +05:30
| `approvals_required` | integer | ** {check-circle}** Yes | The number of required approvals for this rule. |
| `merge_request_iid` | integer | ** {check-circle}** Yes | The IID of the merge request. |
| `name` | string | ** {check-circle}** Yes | The name of the approval rule. |
| `approval_project_rule_id` | integer | ** {dotted-circle}** No | The ID of a project-level approval rule. |
| `group_ids` | Array | ** {dotted-circle}** No | The IDs of groups as approvers. |
| `user_ids` | Array | ** {dotted-circle}** No | The IDs of users as approvers. |
| `usernames` | string array | ** {dotted-circle}** No | The usernames for this rule. |
2019-12-04 20:38:33 +05:30
**Important:** When `approval_project_rule_id` is set, the `name` , `users` and
2021-04-17 20:07:23 +05:30
`groups` of project-level rule are copied. The `approvals_required` specified
is used.
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,
"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
2022-10-11 01:57:18 +05:30
> Moved to GitLab Premium in 13.9.
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
```
2021-04-17 20:07:23 +05:30
**Important:** Approvers and groups not in the `users` /`groups` parameters are **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.
2022-10-11 01:57:18 +05:30
Supported attributes:
2019-12-04 20:38:33 +05:30
2023-03-17 16:20:25 +05:30
| Attribute | Type | Required | Description |
|------------------------|-------------------|------------------------|-------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer or string | ** {check-circle}** Yes | The ID or [URL-encoded path of a project ](rest/index.md#namespaced-path-encoding ). |
2023-03-17 16:20:25 +05:30
| `approval_rule_id` | integer | ** {check-circle}** Yes | The ID of an approval rule. |
| `merge_request_iid` | integer | ** {check-circle}** Yes | The IID of a merge request. |
2023-07-09 08:55:56 +05:30
| `approvals_required` | integer | ** {check-circle}** No | The number of required approvals for this rule. |
2023-03-17 16:20:25 +05:30
| `group_ids` | Array | ** {dotted-circle}** No | The IDs of groups as approvers. |
2023-07-09 08:55:56 +05:30
| `name` | string | ** {check-circle}** No | The name of the approval rule. |
2023-03-17 16:20:25 +05:30
| `remove_hidden_groups` | boolean | ** {dotted-circle}** No | Whether hidden groups should be removed. |
| `user_ids` | Array | ** {dotted-circle}** No | The IDs of users as approvers. |
| `usernames` | string array | ** {dotted-circle}** No | The usernames for this rule. |
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,
"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
2022-10-11 01:57:18 +05:30
> Moved to GitLab Premium in 13.9.
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.
2022-10-11 01:57:18 +05:30
Supported attributes:
2019-12-04 20:38:33 +05:30
2023-03-17 16:20:25 +05:30
| Attribute | Type | Required | Description |
|---------------------|-------------------|------------------------|-------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer or string | ** {check-circle}** Yes | The ID or [URL-encoded path of a project ](rest/index.md#namespaced-path-encoding ). |
2023-03-17 16:20:25 +05:30
| `approval_rule_id` | integer | ** {check-circle}** Yes | The ID of an approval rule. |
| `merge_request_iid` | integer | ** {check-circle}** Yes | The IID of the merge request. |
2019-12-04 20:38:33 +05:30
2022-04-04 11:22:00 +05:30
## Approve merge request
2019-09-04 21:01:54 +05:30
2021-11-18 22:05:49 +05:30
> Moved to GitLab Premium in 13.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
```
2022-10-11 01:57:18 +05:30
Supported attributes:
2019-09-04 21:01:54 +05:30
2023-03-17 16:20:25 +05:30
| Attribute | Type | Required | Description |
|---------------------|-------------------|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer or string | ** {check-circle}** Yes | The ID or [URL-encoded path of a project ](rest/index.md#namespaced-path-encoding ). |
2023-03-17 16:20:25 +05:30
| `approval_password` | string | ** {dotted-circle}** No | Current user's password. Required if [**Require user password to approve** ](../user/project/merge_requests/approvals/settings.md#require-user-password-to-approve ) is enabled in the project settings. |
| `merge_request_iid` | integer | ** {check-circle}** Yes | The IID of the merge request. |
| `sha` | string | ** {dotted-circle}** No | The `HEAD` of the merge request. |
2019-09-04 21:01:54 +05:30
The `sha` parameter works in the same way as
2022-04-04 11:22:00 +05:30
when [accepting a merge request ](merge_requests.md#merge-a-merge-request ): if it is passed, then it must
2019-09-04 21:01:54 +05:30
match the current HEAD of the merge request for the approval to be added. If it
2021-04-17 20:07:23 +05:30
does not match, the response code is `409` .
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-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
}
}
2021-06-08 01:23:25 +05:30
]
2019-09-04 21:01:54 +05:30
}
```
2022-04-04 11:22:00 +05:30
## Unapprove merge request
2019-09-04 21:01:54 +05:30
2021-11-18 22:05:49 +05:30
> Moved to GitLab Premium in 13.9.
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
```
2022-10-11 01:57:18 +05:30
Supported attributes:
2019-09-04 21:01:54 +05:30
2023-03-17 16:20:25 +05:30
| Attribute | Type | Required | Description |
|---------------------|-------------------|------------------------|-------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer or string | ** {check-circle}** Yes | The ID or [URL-encoded path of a project ](rest/index.md#namespaced-path-encoding ). |
2023-03-17 16:20:25 +05:30
| `merge_request_iid` | integer | ** {check-circle}** Yes | The IID of a merge request. |
2023-07-09 08:55:56 +05:30
## Reset approvals of a merge request
Clear all approvals of merge request.
Available only for [bot users ](../user/project/settings/project_access_tokens.md#bot-users-for-projects )
based on project or group tokens. Users without bot permissions receive a `401 Unauthorized` response.
```plaintext
PUT /projects/:id/merge_requests/:merge_request_iid/reset_approvals
```
| Attribute | Type | Required | Description |
|---------------------|-------------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | ** {check-circle}** Yes | The ID or [URL-encoded path of the project ](rest/index.md#namespaced-path-encoding ) owned by the authenticated user. |
| `merge_request_iid` | integer | ** {check-circle}** Yes | The internal ID of the merge request. |
```shell
curl --request PUT --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/76/merge_requests/1/reset_approvals"
```
