Merge request approvals API | GitLab Docs Skip to main content Go to GitLab Docs homepage What's new? What's new? Get free trial Toggle menu * Use GitLab * GitLab Duo * GitLab Orbit * Extend * Install * Administer * Subscribe * Contribute * Solutions Getting started Tutorials Integrations Webhooks REST API Resources .gitignore (templates) .gitlab-ci.yml (templates) Access requests Agent for Kubernetes AI Catalog admin Alert management Application appearance Application settings Application statistics Applications Attestations Audit events Avatar Branches Broadcast messages Cluster discovery (certificate-based) (deprecated) Code Suggestions Commits Compliance and policy settings Container registry Container virtual registry Custom attributes Database migrations Data management Dependencies Dependency firewall Dependency list export Deploy keys Deploy tokens Deployments Discussions Dockerfile (templates) DORA4 metrics Emoji reactions Environments Epics (deprecated) Error tracking Events Experiments External status checks Feature flags Feature flag user lists Flows Freeze periods Geo nodes (deprecated) Geo sites GitLab Duo Chat completions GitLab Pages GLQL Google Cloud integration Groups Import Instance CI/CD variables Invitations Issues Issues (epic) (deprecated) Issues statistics Jobs Job artifacts Job token scopes Keys License Licenses (templates) Linked epics (deprecated) Links (issue) Links (epic) (deprecated) Lint .gitlab-ci.yml Markdown Maven virtual registry Member roles Merge request approvals Merge request approval settings Merge request context commits Merge requests Merge trains Metadata Model registry Namespaces Notes (comments) Notification settings Orbit Organizations Package registry Pages domains Personal access tokens Pipeline schedules Pipeline trigger tokens Pipelines Plan limits Projects Repositories Repository files Repository submodules Resource group Resource iteration events Resource label events Resource milestone events Resource state events Resource weight events Runners Runner controllers Runner controller tokens Search Search migrations Secrets Manager API Secure files Service accounts Service Ping Sidekiq metrics Sidekiq queues Snippet repository storage moves Snippets Suggestions System hooks Tags To-Do List Token information Topics Users User applications Virtual registries cleanup policies Vulnerabilities Vulnerability archive export Vulnerability export Vulnerability findings Web commits Authentication Third-party clients Deprecations and removals OpenAPI Automate storage management Troubleshooting GraphQL API OAuth 2.0 identity provider API GitLab MCP server GitLab Duo CLI (duo) GitLab CLI (glab) Editor and IDE extensions * GitLab Docs / * Extend / * REST API / * Resources / * Merge request approvals Help us learn about your current experience with the documentation. Take the survey . Merge request approvals API * Tier : Free, Premium, Ultimate * Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated Use this API to manage merge request approvals . All endpoints require authentication. The following endpoints are available on all tiers, including Free: * Approve merge request * Unapprove a merge request * Reset approvals for a merge request * Retrieve approval state for a merge request All other endpoints require Premium or Ultimate, and each one shows its tier. The merge_request_iid and id path parameters must each be a single value. Passing multiple space-separated values (for example, 451 454 458 ) is not supported and returns 400 Bad Request . To act on multiple merge requests, make one request per merge request IID. Approve merge request Approves the specified merge request. The currently authenticated user must be an eligible approver . The sha parameter ensures you re approving the current version of the merge request. If defined, the value must match the merge request s HEAD commit SHA. A mismatch returns a 409 Conflict response. This matches the behavior of accepting a merge request . POST /projects/:id/merge_requests/:merge_request_iid/approve Supported attributes: Attribute Type Required Description id integer or string Yes The ID or URL-encoded path of a project. approval_password string No Current user s password. Required if Require user re-authentication to approve is enabled in the project settings. Always fails if the group or GitLab Self-Managed instance is configured to force SAML authentication. merge_request_iid integer Yes The IID of the merge request. sha string No The HEAD of the merge request. { "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" }, "approved_at" : "2016-06-10T04:21:41.050Z" }, { "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" }, "approved_at" : "2016-06-10T09:17:13.520Z" } ] } Prevent approval resets in automated merge requests If you use the API to create and immediately approve a merge request, your automation might approve the merge request before the commit is fully processed. By default, adding a new commit to a merge request resets any existing approvals . When this happens, the Activity area of the merge request shows a sequence of messages like this: * (botname) approved this merge request 5 minutes ago * (botname) added 1 commit 5 minutes ago * (botname) reset approvals from (botname) by pushing to the branch 5 minutes ago To ensure automated approvals are not applied before commit processing is complete, your automation should add a wait (or sleep ) function until: * The detailed_merge_status attribute is not in either the checking or approvals_syncing states. * The merge request diff contains a patch_id_sha that is not NULL. Unapprove a merge request Removes the approval for the currently authenticated user from a specified merge request. POST /projects/:id/merge_requests/:merge_request_iid/unapprove Supported attributes: Attribute Type Required Description id integer or string Yes The ID or URL-encoded path of a project. merge_request_iid integer Yes The IID of a merge request. Reset approvals for a merge request Resets all approvals for a specified merge request. Available only to bot users with a valid project or group token. Human users receive a 401 Unauthorized response. PUT /projects/:id/merge_requests/:merge_request_iid/reset_approvals Attribute Type Required Description id integer or string Yes The ID or URL-encoded path of the project. merge_request_iid integer Yes The internal ID of the merge request. curl --request PUT \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/76/merge_requests/1/reset_approvals" Approval rules for projects * Tier : Premium, Ultimate * Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated These endpoints apply to projects and their approval rules. All endpoints require authentication. Retrieve approval configuration for a project Retrieves the approval configuration for a project. GET /projects/:id/approvals Supported attributes: Attribute Type Required Description id integer or string Yes The ID or URL-encoded path of a project. { "approvers" : [], // Deprecated in GitLab 12.3, always returns empty "approver_groups" : [], // Deprecated in GitLab 12.3, always returns empty "approvals_before_merge" : 2 , // Deprecated in GitLab 12.3, use Approval Rules instead "reset_approvals_on_push" : true , "selective_code_owner_removals" : false , "disable_overriding_approvers_per_merge_request" : false , "merge_requests_author_approval" : true , "merge_requests_disable_committers_approval" : false , "require_password_to_approve" : true , // Deprecated in 16.9, use require_reauthentication_to_approve instead "require_reauthentication_to_approve" : true } Update approval configuration for a project Updates the approval configuration for a project. The currently authenticated user must be an eligible approver . POST /projects/:id/approvals Supported attributes: Attribute Type Required Description id integer or string Yes The ID or URL-encoded path of a project. approvals_before_merge (deprecated) integer No The number of required approvals before a merge request can merge. Deprecated in GitLab 12.3. Create an approval rule instead. disable_overriding_approvers_per_merge_request boolean No If true , prevents overrides of approvers in a merge request. merge_requests_author_approval boolean No If true , authors can self-approve their own merge requests. merge_requests_disable_committers_approval boolean No If true , users who commit on a merge request cannot approve it. require_password_to_approve (deprecated) boolean No If true , require approvers to authenticate with a password before adding the approval. Deprecated in GitLab 16.9. Use require_reauthentication_to_approve instead. require_reauthentication_to_approve boolean No If true , requires approver to authenticate before adding the approval. Introduced in GitLab 17.1. reset_approvals_on_push boolean No If true , approvals are reset on push. selective_code_owner_removals boolean No If true , resets approvals from Code Owners if their files change. To use this field, reset_approvals_on_push must be false . { "approvals_before_merge" : 2 , // Use Approval Rules instead "reset_approvals_on_push" : true , "selective_code_owner_removals" : false , "disable_overriding_approvers_per_merge_request" : false , "merge_requests_author_approval" : false , "merge_requests_disable_committers_approval" : false , "require_password_to_approve" : true , "require_reauthentication_to_approve" : true } List all approval rules for a project Lists all approval rules and any associated details for a specified project. GET /projects/:id/approval_rules To restrict the list of approval rules, use the page and per_page pagination parameters. Supported attributes: Attribute Type Required Description id integer or string Yes The ID or URL-encoded path of a project. Example response: [ { "id" : 1 , "name" : "security" , "rule_type" : "regular" , "report_type" : null , "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 } ], "applies_to_all_protected_branches" : false , "protected_branches" : [ { "id" : 1 , "name" : "main" , "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 , }, { "id" : 2 , "name" : "Coverage-Check" , "rule_type" : "report_approver" , "report_type" : "code_coverage" , "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 } ], "applies_to_all_protected_branches" : false , "protected_branches" : [ { "id" : 1 , "name" : "main" , "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 , } ] Each object in the response includes an eligible_approvers array. The array lists the users who can approve a merge request the rule applies to. Eligible approvers depend on the rule s configuration and on project and group membership. For more information, see eligible approvers . Retrieve an approval rule for a project Retrieves information about a specified approval rule for a project. GET /projects/:id/approval_rules/:approval_rule_id Supported attributes: Attribute Type Required Description id integer or string Yes The ID or URL-encoded path of a project. approval_rule_id integer Yes The ID of an approval rule. { "id" : 1 , "name" : "security" , "rule_type" : "regular" , "report_type" : null , "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 } ], "applies_to_all_protected_branches" : false , "protected_branches" : [ { "id" : 1 , "name" : "main" , "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 } Create an approval rule for a project Creates an approval rule for a project. The rule_type field supports these rule types: * any_approver : A pre-configured default rule with approvals_required set to 0 . * regular : Used for regular merge request approval rules . * report_approver : Used when GitLab creates an approval rule from configured and enabled merge request approval policies . Do not use this value when creating approval rules with this API. POST /projects/:id/approval_rules Supported attributes: Attribute Type Required Description id integer or string Yes The ID or URL-encoded path of a project. approvals_required integer Yes The number of required approvals for this rule. name string Yes The name of the approval rule. Limited to 1024 characters. applies_to_all_protected_branches boolean No If true , applies the rule to all protected branches and ignores the protected_branch_ids attribute. group_ids Array No The IDs of groups as approvers. protected_branch_ids Array No The IDs of protected branches to scope the rule by. To identify the ID, use the List protected branches API. report_type string No The report type. Required when the rule type is report_approver . The supported report types are license_scanning (Deprecated in GitLab 15.9) and code_coverage . rule_type string No The rule type. Supported values include any_approver , regular , and report_approver . user_ids Array No The IDs of users as approvers. If used with usernames , adds both lists of users. usernames string array No The usernames of approvers. If used with user_ids , adds both lists of users. { "id" : 1 , "name" : "security" , "rule_type" : "regular" , "eligible_approvers" : [ { "id" : 2 , "name" : "John Doe" , "username" : "jdoe" , "state" : "active" , "a