Get Gitar's blocking status for a GitLab MR

GET

external

gitlab

mr_status

curl --request GET \
  --url https://api.gitar.ai/v1/external/gitlab/mr_status \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.gitar.ai/v1/external/gitlab/mr_status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gitar.ai/v1/external/gitlab/mr_status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gitar.ai/v1/external/gitlab/mr_status"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.gitar.ai/v1/external/gitlab/mr_status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "blocked": "yes"
}

{
  "message": "<string>",
  "error_code": "<string>"
}

{
  "message": "<string>",
  "error_code": "<string>"
}

{
  "message": "<string>",
  "error_code": "<string>"
}

{
  "message": "<string>",
  "error_code": "<string>"
}

{
  "message": "<string>",
  "error_code": "<string>"
}

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, turn on Settings → Merge requests → Merge checks → Pipelines must succeed in your GitLab project. A failing gitar-check job fails the pipeline, and GitLab then refuses the merge. This works on every GitLab tier, which is the point: merge-request approval rules, the mechanism Gitar uses by default, are a Premium and Ultimate feature.

“Pipelines must succeed” gates on the whole pipeline, not on this job alone, so a pipeline that fails for an unrelated reason also blocks the merge. If you want a gate scoped to Gitar alone and you are on Premium or Ultimate, Gitar’s own approval rule already gives you that and you do not need this job.

Multiple GitLab instances

If your organization has connected more than one GitLab instance, add &host=$CI_SERVER_URL to the request. GitLab project IDs are only unique within a single instance, so without a host Gitar may match a same-numbered project on your other instance — and report pending for a merge request that is actually blocked.

"https://api.gitar.ai/v1/external/gitlab/mr_status?project_id=$CI_PROJECT_ID&mr_iid=$CI_MERGE_REQUEST_IID&host=$CI_SERVER_URL"

CI_SERVER_URL is a predefined GitLab CI/CD variable holding the URL of the instance running the pipeline, so the same job definition works on every instance. Organizations with a single connected instance can omit it.

Blocking Status Values

Value	Meaning
`yes`	Gitar found issues. The CI job fails and the MR cannot be merged.
`no`	Gitar approved the MR, or a human bypassed the block. The CI job passes.
`pending`	Gitar 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

host

string

GitLab instance the project lives on (e.g. https://gitlab.com). Required on multi-instance organizations when the project id is ambiguous.

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

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>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.gitar.ai/v1/external/gitlab/mr_status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gitar.ai/v1/external/gitlab/mr_status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gitar.ai/v1/external/gitlab/mr_status"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.gitar.ai/v1/external/gitlab/mr_status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "blocked": "yes"
}

{
  "message": "<string>",
  "error_code": "<string>"
}

{
  "message": "<string>",
  "error_code": "<string>"
}

{
  "message": "<string>",
  "error_code": "<string>"
}

{
  "message": "<string>",
  "error_code": "<string>"
}

{
  "message": "<string>",
  "error_code": "<string>"
}

API Reference

GitLab API

Installation API

Get Gitar's blocking status for a GitLab MR

Overview

Prerequisites

Setting Up the CI Job

Multiple GitLab instances

Blocking Status Values

Bypassing a Block

Authorizations

Query Parameters

Response

​Overview

​Prerequisites

​Setting Up the CI Job

​Multiple GitLab instances

​Blocking Status Values

​Bypassing a Block

Authorizations

Query Parameters

Response

Overview

Prerequisites

Setting Up the CI Job

Multiple GitLab instances

Blocking Status Values

Bypassing a Block