Skip to main content
GET
/
external
/
gitlab
/
mr_status
Get Gitar's blocking status for a GitLab MR
curl --request GET \
  --url https://api.gitar.ai/v1/external/gitlab/mr_status \
  --header 'Authorization: Bearer <token>'
{}

​
Overview

This endpoint returns Gitar’s current blocking status for a GitLab merge request. It is designed for use in CI pipelines: the pipeline job fails when blocked is "yes", and passes otherwise. By marking this job as required for merge in your GitLab project settings, you get effective merge blocking without needing GitLab approval rule API access.

​
Prerequisites

  • The GitLab project must be connected to Gitar. See Connect GitLab.
  • You need a Gitar API token with integrations:read scope. Store it as a CI/CD variable (e.g. GITAR_TOKEN) in your GitLab project settings.

​
Setting Up the CI Job

Add the following job to your .gitlab-ci.yml: 
gitar-check:
  stage: test
  script:
    - |
      BLOCKED=$(curl -sf -H "Authorization: Bearer $GITAR_TOKEN" \
        "https://api.gitar.ai/v1/external/gitlab/mr_status?project_id=$CI_PROJECT_ID&mr_iid=$CI_MERGE_REQUEST_IID" \
        | python3 -c "import sys,json; print(json.load(sys.stdin)['blocked'])")
      echo "Gitar blocking status: $BLOCKED"
      if [ "$BLOCKED" = "yes" ]; then
        echo "This MR is blocked by Gitar. Resolve the findings or comment 'gitar unblock' to bypass."
        exit 1
      fi
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
CI_PROJECT_ID, CI_MERGE_REQUEST_IID, and CI_PIPELINE_SOURCE are predefined GitLab CI/CD variables automatically available in every pipeline. You do not need to set these yourself.
Once the job is added, go to your GitLab project settings under Settings > Merge requests and mark gitar-check as a required status check. This prevents merging when the job fails.

​
Blocking Status Values

ValueMeaning
yesGitar found issues. The CI job fails and the MR cannot be merged.
noGitar approved the MR, or a human bypassed the block. The CI job passes.
pendingGitar has not reviewed this MR yet. The CI job passes by default.

​
Bypassing a Block

If a merge request is blocked but needs to be merged urgently, a team member can comment gitar unblock on the MR. Gitar will process the command, update the status, and automatically re-trigger the pipeline. The gitar-check job will then pick up the new status and pass, allowing the MR to be merged.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
project_id
integer<int64>
required

GitLab project ID

Required range: x >= 0
​
mr_iid
integer<int64>
required

GitLab merge request IID

Required range: x >= 0

Response

MR blocking status returned successfully

Pipeline-friendly MR status returned to SoFi's CI job.

​
blocked
enum<string>
required

yes → CI job should fail; no → approved or human bypass, pass; pending → no review yet, pass.

Available options:
yes,
no,
pending