外部状态检查
- 层级：Ultimate
- 提供方式：GitLab.com, GitLab Self-Managed, GitLab Dedicated
状态检查是对外部系统的 API 调用，用于请求外部需求的状态。
你可以创建一个状态检查，将合并请求数据发送到第三方工具。 当用户创建、更改或关闭合并请求时，GitLab 会发送通知。用户或自动化工作流随后可以从 GitLab 外部更新合并请求的状态。
通过此集成，你可以与第三方工作流工具（如 ServiceNow）或你选择的自定义工具集成。第三方工具会返回一个关联的状态。该状态随后会作为非阻塞的小部件显示在合并请求中，直接向合并请求的作者或审查者展示此状态。
你可以为每个独立的项目配置合并请求状态检查。这些配置不会在项目之间共享。
如果状态检查在 pending 状态下停留超过两分钟，则检查失败。
访问权限
外部状态检查响应可由以下人员查看：
- 项目中具有 Reporter 角色或更高权限的用户
- 当项目设置为内部可见时，任何可以查看该合并请求的已认证用户
这意味着，如果你有一个内部项目，任何可以访问该合并请求的登录用户都可以查看外部状态检查的响应。
有关用例、功能发现和开发时间表的更多信息，请参阅 epic 3869。
除非所有状态检查都已通过，否则阻止合并请求的合并
默认情况下，即使外部状态检查失败，项目中的合并请求也可以被合并。要在外部检查失败时阻止合并请求的合并：
- 在左侧边栏，选择 搜索或跳转至 并找到你的项目。
- 选择 设置 > 合并请求。
- 勾选 状态检查必须成功 复选框。
- 选择 保存更改。
生命周期
外部状态检查采用 异步 工作流。每当发生以下情况时，合并请求都会向外部服务发送合并请求 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 负载先被发送。
查看状态检查服务
要从合并请求设置中查看添加到项目的状态检查服务列表：
- 在左侧边栏，选择 搜索或跳转至 并找到你的项目。
- 选择 设置 > 合并请求。
- 向下滚动到 状态检查。此列表显示服务名称、API URL、目标分支和 HMAC 认证状态。
你还可以从 分支规则 设置中查看状态检查服务列表。
添加或更新状态检查服务
添加状态检查服务
在 状态检查 子部分中，选择 添加状态检查 按钮。随即会显示 添加状态检查 表单。
填写表单并选择 添加状态检查 按钮即可创建新的状态检查。
此状态检查将应用于所有新的合并请求，但不会追溯应用于现有的合并请求。
更新状态检查服务
在 状态检查 子部分中，选择要编辑的状态检查旁边的 编辑 ( )。随即会显示 更新状态检查 表单。
你无法查看或修改 HMAC 共享密钥的值。要更改共享密钥，请删除并重新创建外部状态检查，并为共享密钥设置一个新值。
要更新状态检查，请在表单中更改值，然后选择 更新状态检查。
状态检查的更新将应用于所有新的合并请求，但不会追溯应用于现有的合并请求。
表单值
有关常见表单错误，请参阅下方的 故障排除 部分。
服务名称
此名称可以是任何字母数字值，并且 必须 设置。该名称 必须 在项目中是唯一的。该名称 必须 在项目中是唯一的。
要检查的 API
此字段需要一个 URL，并且 必须 使用 HTTP 或 HTTPS 协议。我们 建议 使用 HTTPS 来保护传输中的合并请求数据。该 URL 必须 设置，并且 必须 在项目中是唯一的。
目标分支
如果你想将状态检查限制在单个分支，可以使用此字段设置此限制。
分支列表是从项目的 受保护分支 中填充的。
当分支很多且你正在查找的分支没有立即显示时，你可以滚动浏览分支列表或使用搜索框。搜索框需要输入 三个 字母数字字符才能开始搜索。
如果希望状态检查应用于 所有 合并请求，可以选择 所有分支 选项。
HMAC 共享密钥
HMAC 认证可以防止请求被篡改，并确保它们来自合法的来源。
删除状态检查服务
在 状态检查 子部分中，选择要删除的状态检查旁边的 移除 ( )。随即会显示 移除状态检查？ 模态框。
要完成状态检查的删除，你必须选择 移除状态检查 按钮。这将 永久 删除状态检查，并且 无法 恢复。
状态检查小部件
状态检查小部件显示在合并请求中，并显示以下状态：
- pending ( )，当 GitLab 等待来自外部状态检查的响应时。
- success ( ) 或 failed ( )，当 GitLab 收到来自外部状态检查的响应时。
当存在待处理的状态检查时，小部件会每隔几秒轮询一次更新，直到收到 success 或 failed 响应。
要重试失败的状态检查：
- 在左侧边栏，选择 搜索或跳转至 并找到你的项目。
- 选择 代码 > 合并请求 并找到你的合并请求。
- 滚动到合并请求报告部分，展开下拉列表以显示外部状态检查列表。
- 在失败的外部状态检查行上选择 重试 ( )。该状态检查将被重新置于待处理状态。
一个组织可能有这样的策略：如果外部状态检查未通过，则不允许合并合并请求。但是，小部件中的信息仅供参考。
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 返回了意外的响应。按照建议，你应该关闭表单并重新打开或刷新页面。此错误应该是暂时的，但如果持续存在，请检查 GitLab 状态页面 以查看是否有更广泛的故障。
加载状态检查失败
Failed to load status checks外部状态检查 API 返回了意外的响应。你应该：
- 如果此错误是暂时的，请刷新页面。
- 如果问题持续存在，请检查 GitLab 状态页面 以查看是否有更广泛的故障。