External controls API
- Tier: Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Use the external controls API to set the status of a check that uses an external service.
You can configure external controls with periodic ping functionality. When ping is enabled (default), GitLab automatically resets the control status to pending every 12 hours. When ping is disabled, the control status is updated only through API calls.
Set status of an external control
For a single external control, use the API to inform GitLab that a control has passed or failed a check by an external service.
Authentication
External controls API requires HMAC, Timestamp, and Nonce authentication for security.
Endpoint
PATCH /api/v4/projects/:id/compliance_external_controls/:external_control_id/statusHTTP Headers:
| Header | Type | Required | Description |
|---|---|---|---|
X-Gitlab-Timestamp | string | yes | Current Unix timestamp. |
X-Gitlab-Nonce | string | yes | Random string or token to prevent replay attacks. |
X-Gitlab-Hmac-Sha256 | string | yes | HMAC-SHA256 signature of the request. |
Supported attributes:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer | yes | ID of a project. |
external_control_id | integer | yes | ID of an external control. |
status | string | yes | Set to pass to mark the control as passed, or fail to fail it. |
If successful, returns 200 OK and the following
response attributes:
| Attribute | Type | Description |
|---|---|---|
status | string | The status that has been set for the control. |
Example request:
curl --request PATCH \
--header "PRIVATE-TOKEN: <your_access_token>" \
--header "X-Gitlab-Timestamp: <X-Gitlab-Timestamp>" \
--header "X-Gitlab-Nonce: <X-Gitlab-Nonce>" \
--header "X-Gitlab-Hmac-Sha256: <X-Gitlab-Hmac-Sha256>" \
--header "Content-Type: application/json" \
--data '{"status": "pass"}' \
--url "https://gitlab.example.com/api/v4/projects/<id>/compliance_external_controls/<external_control_id>/status"Example response:
{
"status":"pass"
}