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.

Set status of an external control

History

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

POST /api/v4/projects/:id/compliance_external_controls/:external_control_id/status

HTTP Headers:

HeaderTypeRequiredDescription
X-Gitlab-TimestampstringyesCurrent Unix timestamp.
X-Gitlab-NoncestringyesRandom string or token to prevent replay attacks.
X-Gitlab-Hmac-Sha256stringyesHMAC-SHA256 signature of the request.

Supported attributes:

AttributeTypeRequiredDescription
idintegeryesID of a project.
external_control_idintegeryesID of an external control.
statusstringyesSet to pass to mark the control as passed, or fail to fail it.

If successful, returns 200 OK and the following response attributes:

AttributeTypeDescription
statusstringThe status that has been set for the control.

Example request:

curl --request POST \
  --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"
}