Merge request approvals API

原文：https://docs.gitlab.com/ee/api/merge_request_approvals.html

Merge request approvals API

配置项目中所有合并请求（MR）的批准. 必须对所有端点进行身份验证.

Project-level MR approvals

Get Configuration

Introduced in GitLab Starter 10.6.

您可以使用以下端点请求有关项目批准配置的信息：

  1. GET /projects/:id/approvals

Parameters:

Attribute Type Required Description
id integer yes 项目 ID 
  1. {  "approvals_before_merge":  2,  "reset_approvals_on_push":  true,  "disable_overriding_approvers_per_merge_request":  false,  "merge_requests_author_approval":  true,  "merge_requests_disable_committers_approval":  false,  "require_password_to_approve":  true  }

Change configuration

Introduced in GitLab Starter 10.6.

如果允许，则可以使用以下端点更改批准配置：

  1. POST /projects/:id/approvals

Parameters:

Attribute Type Required Description
id integer yes 项目 ID
approvals_before_merge integer no MR 可以合并之前需要多少批准. 在 12.0 中已弃用，以支持批准规则 API.
reset_approvals_on_push boolean no 重置批准以进行新的推送
disable_overriding_approvers_per_merge_request boolean no 允许/禁止每个 MR 的替代批准者
merge_requests_author_approval boolean no 允许/禁止作者自行批准合并请求； true表示作者可以自行批准
merge_requests_disable_committers_approval boolean no 允许/禁止提交者自我批准合并请求
require_password_to_approve boolean no 在添加批准之前，需要批准者输入密码才能进行身份验证 
  1. {  "approvals_before_merge":  2,  "reset_approvals_on_push":  true,  "disable_overriding_approvers_per_merge_request":  false,  "merge_requests_author_approval":  false,  "merge_requests_disable_committers_approval":  false,  "require_password_to_approve":  true  }

Get project-level rules

版本历史

您可以使用以下端点请求有关项目批准规则的信息：

  1. GET /projects/:id/approval_rules

Parameters:

Attribute Type Required Description
id integer yes 项目 ID 
  1. [  {  "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  }  ],  "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  }  ]

Create project-level rule

Introduced in GitLab Starter 12.3.

您可以使用以下端点创建项目批准规则：

  1. POST /projects/:id/approval_rules

Parameters:

Attribute Type Required Description
id integer yes 项目 ID
name string yes 批准规则的名称
approvals_required integer yes 此规则所需的批准数量
user_ids Array no 批准者的用户 ID
group_ids Array no 小组的 ID 为批准者
protected_branch_ids Array no 受保护分支的 ID 范围 
  1. {  "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  }  ],  "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  }

Update project-level rule

Introduced in GitLab Starter 12.3.

您可以使用以下端点更新项目批准规则：

  1. PUT /projects/:id/approval_rules/:approval_rule_id

重要提示：不在users / groups参数中的批准者和组将被删除

Parameters:

Attribute Type Required Description
id integer yes 项目 ID
approval_rule_id integer yes 批准规则的 ID
name string yes 批准规则的名称
approvals_required integer yes 此规则所需的批准数量
user_ids Array no The ids of users as approvers
group_ids Array no 小组的 ID 为批准者
protected_branch_ids Array no 受保护分支的 ID 范围 
  1. {  "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  }  ],  "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  }

Delete project-level rule

Introduced in GitLab Starter 12.3.

您可以使用以下端点删除项目批准规则：

  1. DELETE /projects/:id/approval_rules/:approval_rule_id

Parameters:

Attribute Type Required Description
id integer yes 项目 ID
approval_rule_id integer yes 批准规则的 ID

Change allowed approvers

注意：此 API 端点已被弃用. 请改用批准规则 API. 在GitLab Starter 10.6 中引入 .

如果允许，则可以使用以下端点更改批准者和批准者组：

  1. PUT /projects/:id/approvers

重要提示：不在请求中的批准者和组将被删除

Parameters:

Attribute Type Required Description
id integer yes 项目 ID
approver_ids Array yes 可以批准 MR 的用户 ID 数组
approver_group_ids Array yes 一组可以批准 MR 的组 ID 
  1. {  "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,  "disable_overriding_approvers_per_merge_request":  false,  "merge_requests_author_approval":  true,  "merge_requests_disable_committers_approval":  false,  "require_password_to_approve":  true  }

Merge Request-level MR approvals

配置特定合并请求的批准. 必须对所有端点进行身份验证.

Get Configuration

在GitLab Starter 8.9 中引入.

您可以使用以下端点来请求有关合并请求的批准状态的信息：

  1. GET /projects/:id/merge_requests/:merge_request_iid/approvals

Parameters:

Attribute Type Required Description
id integer yes 项目 ID
merge_request_iid integer yes MR 的 IID 
  1. {  "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",  "web_url":  "http://localhost:3000/root"  }  }  ],  }

Change approval configuration

Introduced in GitLab Starter 10.6.

如果你被允许，你可以改变approvals_required使用以下端点：

  1. POST /projects/:id/merge_requests/:merge_request_iid/approvals

Parameters:

Attribute Type Required Description
id integer yes 项目 ID
merge_request_iid integer yes MR 的 IID
approvals_required integer yes 可以合并 MR 之前需要获得批准. 在 12.0 中已弃用，以支持批准规则 API. 
  1. {  "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":  []  }

Change allowed approvers for Merge Request

注意：此 API 端点已被弃用. 请改用批准规则 API. 在GitLab Starter 10.6 中引入 .

如果允许，则可以使用以下端点更改批准者和批准者组：

  1. PUT /projects/:id/merge_requests/:merge_request_iid/approvers

重要提示：不在请求中的批准者和组将被删除

Parameters:

Attribute Type Required Description
id integer yes 项目 ID
merge_request_iid integer yes MR 的 IID
approver_ids Array yes 可以批准 MR 的用户 ID 数组
approver_group_ids Array yes 一组可以批准 MR 的组 ID 
  1. {  "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",  "web_url":  "http://localhost:3000/root"  }  }  ],  "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  }  }  ]  }

Get the approval state of merge requests

Introduced in GitLab Starter 12.3.

您可以使用以下端点来请求有关合并请求的批准状态的信息：

  1. GET /projects/:id/merge_requests/:merge_request_iid/approval_state

如果为合并请求创建了合并请求级别规则，则approval_rules_overwritten将为true . 如果不存在，则为false .

这包括有关已经批准的用户的更多信息（ approved_by ），以及规则是否已经批准的（ approved ）.

Parameters:

Attribute Type Required Description
id integer yes 项目 ID
merge_request_iid integer yes MR 的 IID 
  1. {  "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,  "approved":  true,  "overridden":  false  }  ]  }

Get merge request level rules

Introduced in GitLab Starter 12.3.

您可以使用以下端点来请求有关合并请求的批准规则的信息：

  1. GET /projects/:id/merge_requests/:merge_request_iid/approval_rules

Parameters:

Attribute Type Required Description
id integer yes 项目 ID
merge_request_iid integer yes MR 的 IID 
  1. [  {  "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  }  ]

Create merge request level rule

Introduced in GitLab Starter 12.3.

您可以使用以下端点创建合并请求批准规则：

  1. POST /projects/:id/merge_requests/:merge_request_iid/approval_rules

Parameters:

Attribute Type Required Description
id integer yes 项目 ID
merge_request_iid integer yes MR 的 IID
name string yes 批准规则的名称
approvals_required integer yes 此规则所需的批准数量
approval_project_rule_id integer no 项目级批准规则的 ID
user_ids Array no 批准者的用户 ID
group_ids Array no 小组的 ID 为批准者

重要提示：当approval_project_rule_id被设置， name ， users和groups项目级的规则将被复制. 该approvals_required指定将被使用.

  1. {  "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  }  ],  "contains_hidden_groups":  false,  "overridden":  false  }

Update merge request level rule

Introduced in GitLab Starter 12.3.

您可以使用以下端点更新合并请求批准规则：

  1. PUT /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id

重要提示：不在users / groups参数中的批准者和组将被删除

重要提示：不允许更新report_approver或code_owner规则. 这些是系统生成的规则.

Parameters:

Attribute Type Required Description
id integer yes 项目 ID
merge_request_iid integer yes MR 的 ID
approval_rule_id integer yes 批准规则的 ID
name string yes 批准规则的名称
approvals_required integer yes 此规则所需的批准数量
user_ids Array no 批准者的用户 ID
group_ids Array no 小组的 ID 为批准者 
  1. {  "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  }  ],  "contains_hidden_groups":  false,  "overridden":  false  }

Delete merge request level rule

Introduced in GitLab Starter 12.3.

您可以使用以下端点删除合并请求批准规则：

  1. DELETE /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id

重要提示：不允许删除report_approver或code_owner规则. 这些是系统生成的规则.

Parameters:

Attribute Type Required Description
id integer yes 项目 ID
merge_request_iid integer yes MR 的 ID
approval_rule_id integer yes 批准规则的 ID

Approve Merge Request

在GitLab Starter 8.9 中引入.

如果允许，则可以使用以下端点批准合并请求：

  1. POST /projects/:id/merge_requests/:merge_request_iid/approve

Parameters:

Attribute Type Required Description
id integer yes 项目 ID
merge_request_iid integer yes MR 的 IID
sha string no MR 的头
approval_password string no 当前用户的密码. 如果在项目设置中启用了” 需要用户密码批准”，则为必需.

sha参数的工作方式与接受合并请求时的工作方式相同：如果传递了它，则它必须与合并请求的当前 HEAD 匹配才能添加批准. 如果不匹配，则响应代码将为409 .

  1. {  "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"  }  },  {  "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"  }  }  ],  }

Unapprove Merge Request

在GitLab Starter 9.0 中引入.

如果您确实批准了合并请求，则可以使用以下端点取消批准它：

  1. POST /projects/:id/merge_requests/:merge_request_iid/unapprove

Parameters:

Attribute Type Required Description
id integer yes 项目 ID
merge_request_iid integer yes MR 的 IID