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被设置, nameusersgroups项目级的规则将被复制. 该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_approvercode_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_approvercode_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