Skip to content

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

Version 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:

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 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"
}

Related topics