How to Set a Commit Status from GitLab CI

Post an external status to a commit via the GitLab statuses API so a custom gate shows on the pipeline and MR.

POST to the commit statuses API using CI_JOB_TOKEN. The status appears against the pipeline commit with your name (context), letting an external check gate the MR.

Post a status with the API

The job token authenticates the call; name is the context shown on the commit.

perf-gate:
  image: curlimages/curl:8.8.0
  script:
    - |
      curl -sS --request POST \
        --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
        "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/statuses/${CI_COMMIT_SHA}" \
        --data "state=success" \
        --data "name=perf-budget" \
        --data "description=under budget"

Gotchas

• state must be one of pending, running, success, failed, canceled.
• Use a unique name per external check; posting the same name updates that status rather than adding another.
• To make the external status block a merge, require it via the MR pipeline/approval settings - the status alone is informational.

Related guides