> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gitar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Gitar's blocking status for a GitLab MR

> Returns the current Gitar blocking status for a GitLab merge request. Intended for use in CI pipelines: fail the job when `blocked == "yes"` and mark it required for merge.

## 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](/connecting-code/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`:

```yaml theme={null}
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"
```

<Tip>
  `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.
</Tip>

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

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


## OpenAPI

````yaml get /external/gitlab/mr_status
openapi: 3.1.0
info:
  title: Gitar External API
  description: API for managing your Gitar installation and integrations
  contact:
    name: Gitar
    url: https://gitar.ai
    email: noreply@gitar.ai
  license:
    name: ''
  version: 1.0.0
servers:
  - url: https://api.gitar.ai/v1
security: []
paths:
  /external/gitlab/mr_status:
    get:
      tags:
        - GitLab MR Status
      summary: Get Gitar's blocking status for a GitLab MR
      description: >-
        Returns the current Gitar blocking status for a GitLab merge request.
        Intended for use in CI pipelines: fail the job when `blocked == "yes"`
        and mark it required for merge.
      operationId: getGitlabMrStatus
      parameters:
        - name: project_id
          in: query
          description: GitLab project ID
          required: true
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: mr_iid
          in: query
          description: GitLab merge request IID
          required: true
          schema:
            type: integer
            format: int64
            minimum: 0
      responses:
        '200':
          description: MR blocking status returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MrStatusResponse'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseFailure'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseFailure'
        '403':
          description: Insufficient scopes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseFailure'
        '404':
          description: Project not connected to this org
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseFailure'
      security:
        - bearerAuth: []
components:
  schemas:
    MrStatusResponse:
      type: object
      description: Pipeline-friendly MR status returned to SoFi's CI job.
      required:
        - blocked
      properties:
        blocked:
          $ref: '#/components/schemas/MrBlockedStatus'
          description: >-
            `yes` → CI job should fail; `no` → approved or human bypass, pass;
            `pending` → no review yet, pass.
    ResponseFailure:
      type: object
      required:
        - message
      properties:
        error_code:
          type:
            - string
            - 'null'
        message:
          type: string
    MrBlockedStatus:
      type: string
      enum:
        - 'yes'
        - 'no'
        - pending
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````