外部状态检查

  • 引入于 14.0 版本,在功能标志 :ff_external_status_checks 后默认禁用
  • 功能标志移除于 14.1 版本。
  • failed 状态引入于 14.9 版本。

状态检查是对请求外部需求状态的外部系统的 API 调用。

您可以创建一个状态检查,将合并请求数据发送到第三方工具。 当用户创建、更改或关闭合并请求时,极狐GitLab 会发送通知。然后,用户或自动化工作流可以更新来自极狐GitLab 外部的合并请求的状态。

通过这种集成,您可以与第三方工作流工具(如 ServiceNow)或您选择的自定义工具集成。第三方工具以关联状态进行响应。 然后,此状态在合并请求中显示为非阻塞部件,以将此状态显示给合并请求作者或合并请求本身级别的审核者。

缺少状态检查响应不会阻止合并请求的合并。

您可以为每个单独的项目配置合并请求状态检查,不在项目之间共享。

除非所有状态检查都已通过,否则阻止合并请求的合并

引入于 15.5 版本,功能标志为 only_allow_merge_if_all_status_checks_passed。默认禁用。

默认情况下,即使外部状态检查失败,项目中的合并请求也可以合并。要在外部检查失败时阻止合并请求,请使用项目 API 启用此功能。您还必须启用功能标志 only_allow_merge_if_all_status_checks_passed

生命周期

外部状态检查有一个异步工作流程。合并请求在以下情况下,向外部服务发出合并请求 Webhook 有效负载:

  • 合并请求已更改。 例如,标题或描述。
  • 代码被推送到合并请求的源分支。
  • 在合并请求讨论中发表评论。
sequenceDiagram Merge request->>+External service: Merge request payload External service-->>-Merge request: Status check response Note over External service,Merge request: Response includes SHA at HEAD

收到负载后,外部服务可以运行任何所需的进程,然后使用 REST API 将其响应发回合并请求。

合并请求会向任何不引用源分支的当前 HEAD的响应返回 409 Conflict 错误。因此,外部服务可以安全地处理和响应过期的提交。

外部状态检查具有以下状态:

  • pending - 默认状态。来自外部服务的合并请求没有收到任何响应。
  • passed - 已收到来自外部服务的响应,并被其批准。
  • failed - 已收到来自外部服务的响应,并被其拒绝。

如果极狐GitLab 之外发生了某些变化,您可以使用 API 设置外部状态检查的状态。您无需等待先发送合并请求 webhook 有效负载。

在项目上查看状态检查

在每个项目的设置中,您可以看到添加到项目的状态检查服务列表:

  1. 在您的项目中,转到 设置 > 合并请求 部分。
  2. 向下滚动到 状态检查

Status checks list

此列表显示服务名称、API URL 和目标分支。 它还提供了允许您创建、编辑或删除状态检查的操作。

添加或更新状态检查服务

添加状态检查服务

状态检查 子部分中,选择 添加状态检查 按钮。 然后会显示 添加状态检查 表单。

Status checks create form

填写表格并选择 添加状态检查 按钮会创建一个新的状态检查。

更新状态检查服务

状态检查 子部分中,选择要编辑的状态检查旁边的 编辑 按钮。 然后会显示 更新状态检查 表单。

Status checks update form

更改表单中的值并选择 更新状态检查 按钮更新状态检查。

表单值

对于常见的表单错误,请参阅下面的故障排查部分。

Service name

此名称可以是任何包含字母和数字的值,并且 必须 设置。 名称 必须 对项目来说是唯一的。 名称 必须 对项目而言是唯一的。

API to check

此字段需要一个 URL,并且 必须 使用 HTTP 或 HTTPS 协议。 我们 建议 使用 HTTPS 来保护传输中的合并请求数据。 URL 必须 被设置并且必须对于项目来说是唯一的。

目标分支

如果要将状态检查限制为单个分支,可以使用此字段设置此限制。

Status checks branch selector

分支列表是由项目受保护的分支填入的。

当有很多分支并且您要查找的分支没有立即出现时,您可以滚动分支列表或使用搜索框。搜索框需要输入 三个 包含字母和数字的字符才能开始搜索。

如果您希望状态检查应用于 所有 合并请求,您可以选择 所有分支 选项。

删除状态检查服务

状态检查 子部分中,选择要删除的状态检查旁边的 删除… 按钮。 然后会显示 删除状态检查 窗口。

Status checks delete modal

要完成状态检查的删除,您必须选择 删除状态检查 按钮。将 永久 删除状态检查,并且 将无法 恢复。

状态检查部件

  • 引入于 14.1 版本。
  • UI 更新于 15.2 版本。

状态检查部件显示在合并请求中并显示以下状态:

  • 等待中 (),极狐GitLab 等待来自外部状态检查的响应。
  • 成功 () 或 失败 (),极狐GitLab 收到来自外部状态检查的响应。

如果外部状态检查未通过,组织可能具有不允许合并合并请求的策略。但是,部件中的详细信息仅供参考。系统不会阻止合并未通过状态检查的合并请求。

note极狐GitLab 无法保证相关外部服务正确处理外部状态检查。

故障排查

重复值错误

Name is already taken
---
External API is already in use by another status check

在每个项目的基础上,状态检查只能使用一次名称或 API URL。 这些错误意味着此项目状态检查中已使用状态检查名称或 API URL。

您必须在当前状态检查中选择不同的值或更新现有状态检查中的值。

无效 URL 错误

Please provide a valid URL

要检查的 API 字段需要提供的 URL 以使用 HTTP 或 HTTPS 协议。 您必须更新该字段的值以满足此要求。

检索或搜索期间的分支列表错误

Unable to fetch branches list, please close the form and try again

从分支检索 API 收到意外响应。 按照建议,您应该关闭表单并重新打开或刷新页面。此错误应该是暂时的。

无法加载状态检查

Failed to load status checks

从外部状态检查 API 收到意外响应。

您应该:

  • 如果此错误是暂时的,请刷新页面。
  • 如果问题仍然存在,请检查看看是否有更广泛的中断。