当前位置：首页 > article >正文

如何使用极狐GitLab 的外部状态检查功能？

article 2025/10/15 9:07:46

极狐GitLab 是 GitLab 在中国的发行版，关于中文参考文档和资料有：

极狐GitLab 中文文档
极狐GitLab 中文论坛
极狐GitLab 官网

外部状态检查 (ULTIMATE ALL)

pending 状态引入于极狐GitLab 16.5
pending 状态检查的超时时间为两分钟引入于极狐GitLab 16.6。

状态检查是向外部系统发出的API调用，目的是请求外部要求的状态。

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

通过此集成，您可以与第三方工作流工具（如 ServiceNow 或您选择的自定义工具）进行集成。第三方工具响应一个相关的状态。该状态将作为非阻塞小部件显示在合并请求中，显示该状态下合并请求的作者或审阅者，直接在合并请求级别。

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

如果状态检查在两分钟内仍处于 pending 状态，则会失败。

限制合并请求的合并，除非所有状态检查已通过

引入于极狐GitLab 15.5 通过一个标志名为 only_allow_merge_if_all_status_checks_passed。默认禁用。
在 JihuLab.com 启用于 GitLab 15.8。
在私有化部署版本中启用，并且功能标志已移除于极狐GitLab 15.9。

默认情况下，即使外部状态检查失败，项目中的合并请求也可以被合并。要阻止外部检查失败时合并合并请求：

1.在左侧边栏中，选择搜索或转到 并找到您的项目。
2.选择 设置 > 合并请求。
3.选中 状态检查必须成功 复选框。
4.选择 保存更改。

生命周期

外部状态检查有一个异步工作流。每当合并请求被更新、关闭、重新打开、批准、取消批准或合并时，合并请求都会向外部服务发送一个合并请求的 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.选择 设置 > 合并请求。
3.向下滚动到 状态检查。此列表显示了服务名称、API URL、目标分支以及 HMAC 身份验证状态。
在这里插入图片描述

您还可以通过分支规则设置查看状态检查服务列表。

添加或更新状态检查服务

添加状态检查服务

在 状态检查 子部分中，选择 添加状态检查 按钮。然后会显示 添加状态检查 表单。
在这里插入图片描述

填写表单并选择 添加状态检查 按钮后，将创建一个新的状态检查。

更新状态检查服务

在 状态检查 子部分中，选择您想编辑的状态检查旁边的编辑 （{铅笔}）。然后会显示 更新状态检查 表单。

NOTE:您无法查看或修改 HMAC 共享密钥的值。要更改共享密钥，您需要删除并使用新值重新创建外部状态检查。

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

表单值

有关常见表单错误，请参见下面的 故障排除 部分。

服务名称

此名称可以是任何字母数字值，必须设置。名称必须对项目唯一。
该名称必须对项目唯一。

检查 API

此字段需要一个 URL，必须使用 HTTP 或 HTTPS 协议。
我们推荐使用 HTTPS 来保护合并请求数据的传输。
URL 必须设置并且必须对项目唯一。

目标分支

如果您想将状态检查限制为单个分支，可以使用此字段来设置此限制。
在这里插入图片描述

分支列表来自项目的保护分支。

您可以滚动浏览分支列表，或者在有很多分支且您要找的分支未立即出现时使用搜索框。搜索框需要输入三个字符来开始搜索。

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

HMAC 共享密钥

HMAC 身份验证可以防止请求篡改，并确保它们来自合法来源。

删除状态检查服务

在 状态检查 子部分中，选择您想删除的状态检查旁边的 移除（{移除}）。然后会显示 删除状态检查？ 模态框。
在这里插入图片描述

要完成状态检查的删除，您必须选择 移除状态检查 按钮。此操作永久删除状态检查，且 不可恢复。

状态检查小部件

极狐GitLab 15.2 更新了 UI 更新。
极狐GitLab 15.8 添加了重试失败的外部状态检查功能。
极狐GitLab 15.11 更新了小部件更新，以在状态检查待定时轮询更新。

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

待定 ({状态中立})，表示 GitLab 等待来自外部状态检查的响应。
成功 ({状态成功}) 或 失败 ({状态失败})，表示 GitLab 收到来自外部状态检查的响应。

当存在待定的状态检查时，小部件会每隔几秒轮询更新，直到收到成功或失败响应。

要重试失败的状态检查：

1.在左侧边栏中，选择 搜索或跳转 并找到您的项目。
2.选择 代码 > 合并请求 并找到您的合并请求。
3.向下滚动到合并请求报告部分，展开下拉列表显示外部状态检查列表。
4.在失败的外部状态检查行上选择 重试（{重试}）。该状态检查将恢复为待定状态。

一个组织可能有不允许在外部状态检查不通过时合并合并请求的政策。然而，小部件中的详细信息仅供参考。

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

故障排除

重复值错误

名称已被占用
---
外部 API 已被另一个状态检查使用

对于每个项目，状态检查只能使用一次名称或 API URL。

这些错误意味着该项目的状态检查中，名称或 API URL 已经被使用。

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

无效的 URL 错误

请提供有效的url

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

获取或搜索分支时的错误

无法获取分支列表，请关闭表单并再次尝试。

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

您可以尝试以下操作：

刷新页面，以防此错误是暂时性的。
如果问题持续存在，请检查 GitLab 状态页面，查看是否存在更广泛的故障。