极狐 GitLab

外部控制 API

Tier: 旗舰版

Offering: JihuLab.com，私有化部署

使用外部控制 API 来设置使用外部服务的检查状态。

你可以配置带有定期 ping 功能的外部控制。当 ping 启用时（默认），极狐GitLab 每 12 小时自动将控制状态重置为 pending。当 ping 禁用时，控制状态仅通过 API 调用更新。

设置外部控制的状态

版本历史
  • 在极狐GitLab 17.11 中引入。

设置指定外部控制的状态。通过此操作，可告知极狐GitLab 某个控制已通过或未通过外部服务的检查。

先决条件

  • 必须使用 HMAC、Timestamp 和 Nonce 认证以确保安全。
plaintext
PATCH /api/v4/projects/:id/compliance_external_controls/:external_control_id/status

HTTP 请求头：

请求头类型必填描述
X-Gitlab-Timestamp字符串是当前 Unix 时间戳。
X-Gitlab-Nonce字符串是随机字符串或令牌以防止重放攻击。
X-Gitlab-Hmac-Sha256字符串是请求的 HMAC-SHA256 签名。

要计算 HMAC-SHA256 签名：

  1. 按以下顺序连接以下值：
    • X-Gitlab-Timestamp
    • X-Gitlab-Nonce
    • 请求的完整路径
    • status 属性值，格式为 status=<status>
  2. 使用你的密钥计算连接字符串的 HMAC-SHA256。

支持的属性：

属性类型必填描述
id整数是项目的 ID。
external_control_id整数是外部控制的 ID。
status字符串是设置为 pass 将控制标记为通过，或设置为 fail 标记为失败。

如果成功，返回 200 OK 以及以下响应属性：

属性类型描述
status字符串已为控制设置的状态。

请求示例：

shell
1curl --request PATCH \
2  --header "PRIVATE-TOKEN: <your_access_token>" \
3  --header "X-Gitlab-Timestamp: <X-Gitlab-Timestamp>" \
4  --header "X-Gitlab-Nonce: <X-Gitlab-Nonce>" \
5  --header "X-Gitlab-Hmac-Sha256: <X-Gitlab-Hmac-Sha256>" \
6  --header "Content-Type: application/json" \
7  --data '{"status": "pass"}' \
8  --url "https://gitlab.example.com/api/v4/projects/<id>/compliance_external_controls/<external_control_id>/status"

响应示例：

json
{
    "status":"pass"
}