{{< details >}}

  • Tier: 专业版,旗舰版
  • Offering: JihuLab.com,私有化部署

{{< /details >}}

{{< history >}}

  • 端点 /approvals 在极狐GitLab 16.0 中被移除。

{{< /history >}}

项目中所有合并请求的审批配置。所有端点都需要认证。

批准合并请求

具有适当角色的用户可以使用此端点批准合并请求:

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

支持的属性:

属性 类型 必需 描述
id 整数或字符串 项目的 ID 或 URL 编码路径
approval_password 字符串 当前用户的密码。如果在项目设置中启用了Require user re-authentication to approve,则需要。群组或极狐GitLab 私有化部署实例配置为强制 SAML 身份验证时始终失败。
merge_request_iid 整数 合并请求的 IID。
sha 字符串 合并请求的 HEAD

sha 参数的工作原理与接受合并请求时相同:如果传递,则必须匹配合并请求的当前 HEAD 才能添加批准。如果不匹配,响应代码为 409

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

取消批准合并请求

如果您批准了合并请求,可以使用以下端点取消批准:

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

支持的属性:

属性 类型 必需 描述
id 整数或字符串 项目的 ID 或 URL 编码路径
merge_request_iid 整数 合并请求的 IID。

重置合并请求的批准

清除合并请求的所有批准。

仅对基于项目或群组令牌的机器人用户可用。没有机器人权限的用户会收到 401 Unauthorized 响应。

PUT /projects/:id/merge_requests/:merge_request_iid/reset_approvals
属性 类型 必需 描述
id 整数或字符串 项目的 ID 或 URL 编码路径
merge_request_iid 整数 合并请求的内部 ID。
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/76/merge_requests/1/reset_approvals"

项目审批规则

使用项目审批规则来访问此信息。

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

GET /projects/:id/approvals

支持的属性:

属性 类型 必需 描述
id 整数或字符串 项目的 ID 或 URL 编码路径
{
  "approvers": [], // 在极狐GitLab 12.3中弃用,始终返回空
  "approver_groups": [], // 在极狐GitLab 12.3中弃用,始终返回空
  "approvals_before_merge": 2, // 在极狐GitLab 12.3中弃用,改用审批规则
  "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, //  16.9 中弃用,改用 require_reauthentication_to_approve
  "require_reauthentication_to_approve": true
}

更改配置

具有适当角色的用户可以使用此端点更改审批配置:

POST /projects/:id/approvals

支持的属性:

属性 类型 必需 描述
id 整数或字符串 项目的 ID 或 URL 编码路径
approvals_before_merge (弃用) 整数 合并请求可以合并之前所需的批准数量。弃用于极狐GitLab 12.3中。改用审批规则
disable_overriding_approvers_per_merge_request 布尔值 允许或阻止每个合并请求覆盖审批人。
merge_requests_author_approval 布尔值 允许或阻止作者自我批准合并请求;true 表示作者可以自我批准。
merge_requests_disable_committers_approval 布尔值 允许或阻止提交者自我批准合并请求。
require_password_to_approve (弃用) 布尔值 要求审批人在添加批准之前输入密码进行认证。弃用于极狐GitLab 16.9中。改用 require_reauthentication_to_approve
require_reauthentication_to_approve 布尔值 要求审批人在添加批准之前输入进行认证。引入于极狐GitLab 17.1中。
reset_approvals_on_push 布尔值 在新的推送时重置批准。
selective_code_owner_removals 布尔值 如果代码所有者的文件更改,则从代码所有者中重置批准。您必须禁用 reset_approvals_on_push 字段以使用此字段。
{
  "approvals_before_merge": 2, // 改用审批规则
  "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
}

获取项目的所有审批规则

{{< history >}}

  • 分页支持引入于极狐GitLab 15.3,使用名为 approval_rules_pagination功能标志。默认启用。
  • applies_to_all_protected_branches 属性引入于极狐GitLab 15.3。
  • 分页支持在极狐GitLab 15.7 中 GA。功能标志 approval_rules_pagination 被移除。
  • usernames 属性引入于极狐GitLab 15.8。

{{< /history >}}

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

GET /projects/:id/approval_rules

使用 pageper_page 分页 参数来限制审批规则列表。

支持的属性:

属性 类型 必需 描述
id 整数或字符串 项目的 ID 或 URL 编码路径
[
  {
    "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,
  }
]

获取项目的单个审批规则

{{< history >}}

  • applies_to_all_protected_branches 属性引入于极狐GitLab 15.3。
  • usernames 属性引入于极狐GitLab 15.8。

{{< /history >}}

您可以使用以下端点请求有关单个项目的审批规则的信息:

GET /projects/:id/approval_rules/:approval_rule_id

支持的属性:

属性 类型 必需 描述
id 整数或字符串 项目的 ID 或 URL 编码路径
approval_rule_id 整数 审批规则的 ID。
{
  "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
}

创建项目审批规则

{{< history >}}

  • 在极狐GitLab 15.0 中,移除了漏洞检查功能。
  • applies_to_all_protected_branches 属性引入于极狐GitLab 15.3。
  • usernames 属性引入于极狐GitLab 15.8。

{{< /history >}}

您可以使用以下端点创建项目审批规则:

POST /projects/:id/approval_rules

支持的属性:

属性 类型 必需 描述
id 整数或字符串 项目的 ID 或 URL 编码路径
approvals_required 整数 此规则所需的批准数量。
name 字符串 审批规则的名称。限制为 1024 个字符。
applies_to_all_protected_branches 布尔值 是否将规则应用于所有受保护分支。如果设置为 true,则忽略 protected_branch_ids 的值。默认为 false引入于极狐GitLab 15.3中。
group_ids 数组 作为审批人的群组 ID。
protected_branch_ids 数组 受保护分支的 ID,用于限定规则范围。要识别 ID,使用 API
report_type 字符串 当规则类型为 report_approver 时所需的报告类型。支持的报告类型为 license_scanning (弃用于极狐GitLab 15.9)code_coverage
rule_type 字符串 规则类型。any_approver 是一个预配置的默认规则,approvals_required0。其他规则为 regular(用于常规合并请求审批规则)和 report_approver。不要使用此字段从 API 构建审批规则。report_approver 字段用于当极狐GitLab 从配置和启用的合并请求审批策略创建审批规则时。
user_ids 数组 作为审批人的用户 ID。如果您同时提供 user_idsusernames,则会添加两个用户列表。
usernames 字符串数组 此规则的审批人的用户名(与 user_ids 相同,但需要用户名列表)。如果您同时提供 user_idsusernames,则会添加两个用户列表。
{
  "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
    }
  ],
  "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
}

您可以增加默认的 0 个所需审批人数量,如下所示:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header 'Content-Type: application/json' \
  --data '{"name": "Any name", "rule_type": "any_approver", "approvals_required": 2}' \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/approval_rules"

另一个示例是创建用户特定规则:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header 'Content-Type: application/json' \
  --data '{"name": "Name of your rule", "approvals_required": 3, "user_ids": [123, 456, 789]}' \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/approval_rules"

更新项目审批规则

{{< history >}}

  • 在极狐GitLab 15.0 中,移除了漏洞检查功能。
  • applies_to_all_protected_branches 属性引入于极狐GitLab 15.3。
  • usernames 属性引入于极狐GitLab 15.8。

{{< /history >}}

您可以使用以下端点更新项目审批规则:

PUT /projects/:id/approval_rules/:approval_rule_id

{{< alert type=”note” >}}

审批人和群组(除 usersgroups 参数中未包含的隐藏群组外)将被移除。隐藏群组是用户没有权限查看的私人群组。默认情况下,隐藏群组不会被移除,除非 remove_hidden_groups 参数为 true。这确保了在用户更新审批规则时不会无意中移除隐藏群组。

{{< /alert >}}

支持的属性:

属性 类型 必需 描述
id 整数或字符串 项目的 ID 或 URL 编码路径
approvals_required 整数 此规则所需的批准数量。
approval_rule_id 整数 审批规则的 ID。
name 字符串 审批规则的名称。限制为 1024 个字符。
applies_to_all_protected_branches 布尔值 是否将规则应用于所有受保护分支。如果设置为 true,则忽略 protected_branch_ids 的值。引入于极狐GitLab 15.3 中。
group_ids 数组 作为审批人的群组 ID。
protected_branch_ids 数组 受保护分支的 ID,用于限定规则范围。要识别 ID,使用 API
remove_hidden_groups 布尔值 是否从审批规则中移除隐藏群组。
user_ids 数组 作为审批人的用户 ID。如果您同时提供 user_idsusernames,则会添加两个用户列表。
usernames 字符串数组 此规则的审批人的用户名(与 user_ids 相同,但需要用户名列表)。如果您同时提供 user_idsusernames,则会添加两个用户列表。
{
  "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
    }
  ],
  "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
}

删除项目审批规则

您可以使用以下端点删除项目审批规则:

DELETE /projects/:id/approval_rules/:approval_rule_id

支持的属性:

属性 类型 必需 描述
id 整数或字符串 项目的 ID 或 URL 编码路径
approval_rule_id 整数 审批规则的 ID。

单个合并请求审批

特定合并请求的审批配置。所有端点都需要认证。

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

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

支持的属性:

属性 类型 必需 描述
id 整数或字符串 项目的 ID 或 URL 编码路径
merge_request_iid 整数 合并请求的 IID。
{
  "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"
      }
    }
  ]
}

获取合并请求的审批状态

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

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

如果为合并请求创建了合并请求级别规则,则 approval_rules_overwrittentrue。如果没有,则为 false

这包括有关已批准的用户(approved_by)以及某个规则是否已批准(approved)的更多信息。

支持的属性:

属性 类型 必需 描述
id 整数或字符串 项目的 ID 或 URL 编码路径
merge_request_iid 整数 合并请求的 IID。
{
  "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
    }
  ]
}

获取合并请求审批规则

{{< history >}}

  • 分页支持引入于极狐GitLab 15.3,使用名为 approval_rules_pagination功能标志。默认启用。
  • 分页支持在极狐GitLab 15.7 中 GA。功能标志 approval_rules_pagination 被移除。

{{< /history >}}

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

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

使用 pageper_page 分页 参数来限制审批规则列表。

支持的属性:

属性 类型 必需 描述
id 整数或字符串 项目的 ID 或 URL 编码路径
merge_request_iid 整数 合并请求的 IID。
[
  {
    "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,
    "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
  },
  {
    "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,
    "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
  }
]

获取单个合并请求规则

您可以使用以下端点请求有关单个合并请求审批规则的信息:

GET /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id

支持的属性:

属性 类型 必需 描述
id 整数或字符串 项目的 ID 或 URL 编码路径
approval_rule_id 整数 审批规则的 ID。
merge_request_iid 整数 合并请求的 IID。
{
  "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,
  "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
}

创建合并请求规则

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

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

支持的属性:

属性 类型 必需 描述
id integer 或 string 项目的 ID 或 URL 编码路径
approvals_required integer 此规则所需的批准数量。
merge_request_iid integer 合并请求的 IID。
name string 审批规则的名称。限制为 1024 个字符。
approval_project_rule_id integer 项目审批规则的 ID。
group_ids 数组 作为审批者的群组 ID。
user_ids 数组 作为审批者的用户 ID。如果同时提供 user_idsusernames,则添加这两个用户列表。
usernames 字符串数组 此规则的审批者用户名(与 user_ids 相同,但需要用户名列表)。如果同时提供 user_idsusernames,则添加这两个用户列表。

NOTE:

设置 approval_project_rule_id 会复制项目规则的 nameusersgroups。它使用您指定的 approvals_required

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

更新合并请求规则

要更新合并请求审批规则,请使用此端点:

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

此端点移除不在 usersgroups 参数中的任何审批者和群组。

您不能更新 report_approvercode_owner 规则,因为这些规则是系统生成的。

支持的属性:

属性 类型 必需 描述
id integer 或 string 项目的 ID 或 URL 编码路径
approval_rule_id integer 审批规则的 ID。
merge_request_iid integer 合并请求的 IID。
approvals_required integer 此规则所需的批准数量。
group_ids 数组 作为审批者的群组 ID。
name string 审批规则的名称。限制为 1024 个字符。
remove_hidden_groups boolean 是否移除隐藏的群组。
user_ids 数组 作为审批者的用户 ID。如果同时提供 user_idsusernames,则添加这两个用户列表。
usernames 字符串数组 此规则的审批者用户名(与 user_ids 相同,但需要用户名列表)。如果同时提供 user_idsusernames,则添加这两个用户列表。
{
  "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 /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id

您不能更新 report_approvercode_owner 规则,因为这些规则是系统生成的。

支持的属性:

属性 类型 必需 描述
id integer 或 string 项目的 ID 或 URL 编码路径
approval_rule_id integer 审批规则的 ID。
merge_request_iid integer 合并请求的 IID。

群组审批规则

  • 状态:实验

在极狐GitLab 16.7 中引入,有一个名为 approval_group_rules标志。默认情况下禁用。此功能是一个实验

在极狐GitLab 私有化部署中,默认情况下此功能不可用。要使其可用,管理员可以启用名为 approval_group_rules 的功能标志。在 JihuLab.com 和极狐GitLab 专用中,此功能不可用。此功能尚未准备好用于生产环境。

群组审批规则适用于属于该群组的项目的所有受保护分支。此功能是一个实验

获取群组审批规则

在极狐GitLab 16.10 中引入

群组管理员可以使用以下端点请求有关群组审批规则的信息:

GET /groups/:id/approval_rules

使用 pageper_page 分页 参数限制审批规则的列表。

支持的属性:

属性 类型 必需 描述
id integer 或 string 项目的 ID 或 URL 编码路径

示例请求:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/29/approval_rules"

示例响应:

[
  {
    "id": 2,
    "name": "rule1",
    "rule_type": "any_approver",
    "report_type": null,
    "eligible_approvers": [],
    "approvals_required": 3,
    "users": [],
    "groups": [],
    "contains_hidden_groups": false,
    "protected_branches": [],
    "applies_to_all_protected_branches": true
  },
  {
    "id": 3,
    "name": "rule2",
    "rule_type": "code_owner",
    "report_type": null,
    "eligible_approvers": [],
    "approvals_required": 2,
    "users": [],
    "groups": [],
    "contains_hidden_groups": false,
    "protected_branches": [],
    "applies_to_all_protected_branches": true
  },
  {
    "id": 4,
    "name": "rule2",
    "rule_type": "report_approver",
    "report_type": "code_coverage",
    "eligible_approvers": [],
    "approvals_required": 2,
    "users": [],
    "groups": [],
    "contains_hidden_groups": false,
    "protected_branches": [],
    "applies_to_all_protected_branches": true
  }
]

创建群组审批规则

群组管理员可以使用以下端点为群组创建审批规则:

POST /groups/:id/approval_rules

支持的属性:

属性 类型 必需 描述
id integer 或 string 群组的 ID 或 URL 编码路径
approvals_required integer 此规则所需的批准数量。
name string 审批规则的名称。限制为 1024 个字符。
group_ids 数组 作为审批者的群组 ID。
rule_type string 规则类型。any_approver 是一个预配置的默认规则,其 approvals_required0。其他规则是 regular(用于常规合并请求审批规则)和 report_approver。不要使用此字段从 API 构建审批规则。当极狐GitLab 从配置和启用的合并请求审批政策创建审批规则时,使用 report_approver 字段。
user_ids 数组 作为审批者的用户 ID。

示例请求:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/29/approval_rules?name=security&approvals_required=2"

示例响应:

{
  "id": 5,
  "name": "security",
  "rule_type": "any_approver",
  "eligible_approvers": [],
  "approvals_required": 2,
  "users": [],
  "groups": [],
  "contains_hidden_groups": false,
  "protected_branches": [
    {
      "id": 5,
      "name": "master",
      "push_access_levels": [
        {
          "id": 5,
          "access_level": 40,
          "access_level_description": "Maintainers",
          "deploy_key_id": null,
          "user_id": null,
          "group_id": null
        }
      ],
      "merge_access_levels": [
        {
          "id": 5,
          "access_level": 40,
          "access_level_description": "Maintainers",
          "user_id": null,
          "group_id": null
        }
      ],
      "allow_force_push": false,
      "unprotect_access_levels": [],
      "code_owner_approval_required": false,
      "inherited": false
    }
  ],
  "applies_to_all_protected_branches": true
}

更新群组审批规则

在极狐GitLab 16.10 中引入

群组管理员可以使用以下端点更新群组审批规则:

PUT /groups/:id/approval_rules/:approval_rule_id

支持的属性:

属性 类型 必需 描述
approval_rule_id. integer 审批规则的 ID。
id integer 或 string 群组的 ID 或 URL 编码路径
approvals_required string 此规则所需的批准数量。
group_ids integer 作为审批者的用户 ID。
name string 审批规则的名称。限制为 1024 个字符。
rule_type 数组 规则类型。any_approver 是一个预配置的默认规则,其 approvals_required0。其他规则是 regular(用于常规合并请求审批规则)和 report_approver。不要使用此字段从 API 构建审批规则。当极狐GitLab 从配置和启用的合并请求审批政策创建审批规则时,使用 report_approver 字段。
user_ids 数组 作为审批者的群组 ID。

示例请求:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/29/approval_rules/5?name=security2&approvals_required=1"

示例响应:

{
  "id": 5,
  "name": "security2",
  "rule_type": "any_approver",
  "eligible_approvers": [],
  "approvals_required": 1,
  "users": [],
  "groups": [],
  "contains_hidden_groups": false,
  "protected_branches": [
    {
      "id": 5,
      "name": "master",
      "push_access_levels": [
        {
          "id": 5,
          "access_level": 40,
          "access_level_description": "Maintainers",
          "deploy_key_id": null,
          "user_id": null,
          "group_id": null
        }
      ],
      "merge_access_levels": [
        {
          "id": 5,
          "access_level": 40,
          "access_level_description": "Maintainers",
          "user_id": null,
          "group_id": null
        }
      ],
      "allow_force_push": false,
      "unprotect_access_levels": [],
      "code_owner_approval_required": false,
      "inherited": false
    }
  ],
  "applies_to_all_protected_branches": true
}