ContextQMD
Back to Gitlabhq

Merge request approval settings API

doc/api/merge_request_approval_settings.md

18.11.28.2 KB
Original Source

{{< details >}}

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

{{< /details >}}

Use this API to manage group and project merge request approval settings. All endpoints require authentication.

Group MR approval settings

Prerequisites:

  • You must have the Owner role in the group.

Retrieve MR approval settings for a group

Retrieves the merge request approval settings for a specified group.

plaintext
GET /groups/:id/merge_request_approval_setting

Parameters:

AttributeTypeRequiredDescription
idinteger or stringYesID or URL-encoded path of the group.

Example request:

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

Example response:

json
{
  "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.

plaintext
PUT /groups/:id/merge_request_approval_setting

Parameters:

AttributeTypeRequiredDescription
idinteger or stringYesID or URL-encoded path of the group.
allow_author_approvalbooleanNoAllow or prevent authors from self approving merge requests; true means authors can self approve.
allow_committer_approvalbooleanNoAllow or prevent committers from self approving merge requests.
allow_overrides_to_approver_list_per_merge_requestbooleanNoAllow or prevent overriding approvers per merge request.
retain_approvals_on_pushbooleanNoRetain approval count on a new push.
require_reauthentication_to_approvebooleanNoRequire approver to authenticate before adding the approval. Introduced in GitLab 17.1.

Example request:

shell
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:

json
{
  "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.

Retrieve MR approval settings for a project

Retrieves the merge request approval settings for a specified project.

plaintext
GET /projects/:id/merge_request_approval_setting

Parameters:

AttributeTypeRequiredDescription
idinteger or stringYesID or URL-encoded path of the project.

Example request:

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

Example response:

json
{
  "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.

plaintext
PUT /projects/:id/merge_request_approval_setting

Parameters:

AttributeTypeRequiredDescription
idinteger or stringYesID or URL-encoded path of the group.
allow_author_approvalbooleanNoAllow or prevent authors from self approving merge requests; true means authors can self approve.
allow_committer_approvalbooleanNoAllow or prevent committers from self approving merge requests.
allow_overrides_to_approver_list_per_merge_requestbooleanNoAllow or prevent overriding approvers per merge request.
retain_approvals_on_pushbooleanNoRetain approval count on a new push.
selective_code_owner_removalsbooleanNoReset approvals from Code Owners if their files changed. You must disable the retain_approvals_on_push field to use this field.
require_reauthentication_to_approvebooleanNoRequire approver to authenticate before adding the approval. Introduced in GitLab 17.1.

Example request:

shell
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:

json
{
  "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
  }
}