Merge request approval settings API

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Configuration for approval settings on all merge requests in a group or project. All endpoints require authentication.

Group MR approval settings

Prerequisites:

You must have the Owner role in the group.

Get group MR approval settings

Get the merge request approval settings of a group.

GET /groups/:id/merge_request_approval_setting

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the group.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/merge_request_approval_setting"

Example response:

{
  "allow_author_approval": {
    "value": true,
    "locked": false,
    "inherited_from": null
  },
  "allow_committer_approval": {
    "value": true,
    "locked": false,
    "inherited_from": null
  },
  "allow_overrides_to_approver_list_per_merge_request": {
    "value": true,
    "locked": false,
    "inherited_from": null
  },
  "retain_approvals_on_push": {
    "value": false,
    "locked": false,
    "inherited_from": null
  },
  "selective_code_owner_removals": {
    "value": false,
    "locked": false,
    "inherited_from": null
  },
  "require_password_to_approve": {
    "value": false,
    "locked": false,
    "inherited_from": null
  },
  "require_reauthentication_to_approve": {
    "value": false,
    "locked": false,
    "inherited_from": null
  }
}

Update group MR approval settings

Update the merge request approval settings of a group.

PUT /groups/:id/merge_request_approval_setting

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the group.
`allow_author_approval`	boolean	No	Allow or prevent authors from self approving merge requests; `true` means authors can self approve.
`allow_committer_approval`	boolean	No	Allow or prevent committers from self approving merge requests.
`allow_overrides_to_approver_list_per_merge_request`	boolean	No	Allow or prevent overriding approvers per merge request.
`retain_approvals_on_push`	boolean	No	Retain approval count on a new push.
`selective_code_owner_removals`	boolean	No	Reset approvals from Code Owners if their files changed. You must disable the `retain_approvals_on_push` field to use this field.
`require_reauthentication_to_approve`	boolean	No	Require approver to authenticate before adding the approval. Introduced in GitLab 17.1.

Example request:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/merge_request_approval_setting?allow_author_approval=false"

Example response:

{
  "allow_author_approval": {
    "value": false,
    "locked": false,
    "inherited_from": null
  },
  "allow_committer_approval": {
    "value": true,
    "locked": false,
    "inherited_from": null
  },
  "allow_overrides_to_approver_list_per_merge_request": {
    "value": true,
    "locked": false,
    "inherited_from": null
  },
  "retain_approvals_on_push": {
    "value": false,
    "locked": false,
    "inherited_from": null
  },
  "selective_code_owner_removals": {
    "value": false,
    "locked": false,
    "inherited_from": null
  },
  "require_password_to_approve": {
    "value": false,
    "locked": false,
    "inherited_from": null
  },
  "require_reauthentication_to_approve": {
    "value": false,
    "locked": false,
    "inherited_from": null
  }
}

Project MR approval settings

Prerequisites:

You must have the Maintainer role in the project.

Get project MR approval settings

Get the merge request approval settings of a project.

GET /projects/:id/merge_request_approval_setting

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/:id/merge_request_approval_setting"

Example response:

{
  "allow_author_approval": {
    "value": true,
    "locked": false,
    "inherited_from": null
  },
  "allow_committer_approval": {
    "value": true,
    "locked": false,
    "inherited_from": null
  },
  "allow_overrides_to_approver_list_per_merge_request": {
    "value": true,
    "locked": false,
    "inherited_from": null
  },
  "retain_approvals_on_push": {
    "value": false,
    "locked": true,
    "inherited_from": "group"
  },
  "selective_code_owner_removals": {
    "value": false,
    "locked": false,
    "inherited_from": null
  },
  "require_password_to_approve": {
    "value": false,
    "locked": false,
    "inherited_from": null
  },
  "require_reauthentication_to_approve": {
    "value": false,
    "locked": false,
    "inherited_from": null
  }
}

Update project MR approval settings

Update the merge request approval settings of a project.

PUT /projects/:id/merge_request_approval_setting

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the group.
`allow_author_approval`	boolean	No	Allow or prevent authors from self approving merge requests; `true` means authors can self approve.
`allow_committer_approval`	boolean	No	Allow or prevent committers from self approving merge requests.
`allow_overrides_to_approver_list_per_merge_request`	boolean	No	Allow or prevent overriding approvers per merge request.
`retain_approvals_on_push`	boolean	No	Retain approval count on a new push.
`selective_code_owner_removals`	boolean	No	Reset approvals from Code Owners if their files changed. You must disable the `retain_approvals_on_push` field to use this field.
`require_reauthentication_to_approve`	boolean	No	Require approver to authenticate before adding the approval. Introduced in GitLab 17.1.

Example request:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/:id/merge_request_approval_setting?allow_author_approval=false"

Example response:

{
  "allow_author_approval": {
    "value": false,
    "locked": false,
    "inherited_from": null
  },
  "allow_committer_approval": {
    "value": true,
    "locked": false,
    "inherited_from": null
  },
  "allow_overrides_to_approver_list_per_merge_request": {
    "value": true,
    "locked": false,
    "inherited_from": null
  },
  "retain_approvals_on_push": {
    "value": false,
    "locked": false,
    "inherited_from": null
  },
  "selective_code_owner_removals": {
    "value": false,
    "locked": false,
    "inherited_from": null
  },
  "require_password_to_approve": {
    "value": false,
    "locked": false,
    "inherited_from": null
  },
  "require_reauthentication_to_approve": {
    "value": false,
    "locked": false,
    "inherited_from": null
  }
}

Docs

Edit this page to fix an error or add an improvement in a merge request.

Create an issue to suggest an improvement to this page.

Product

Create an issue if there's something you don't like about this feature.

Propose functionality by submitting a feature request.

Feature availability and product trials

View pricing to see all GitLab tiers and features, or to upgrade.

Try GitLab for free with access to all features for 30 days.

Get help

If you didn't find what you were looking for, search the docs.

If you want help with something specific and could use community support, post on the GitLab forum.

For problems setting up or using this feature (depending on your GitLab subscription).

Request support

Merge request approval settings API

Group MR approval settings

Get group MR approval settings

Update group MR approval settings

Project MR approval settings

Get project MR approval settings

Update project MR approval settings

Help & feedback

Docs

Product

Feature availability and product trials

Get help