GitLab: Advanced Example¶

Production-ready configuration with all best practices.

Step 1: Create a Personal Access Token (PAT)¶

User Settings → Access Tokens → Add new token

Field	Value
Name	`ai-code-reviewer`
Scopes	`api`
Expiration	As needed

Free plan

Personal Access Token works on all GitLab plans, including Free.

Project Access Token is only available on GitLab Premium/Ultimate.

Step 2: Add Variables¶

Settings → CI/CD → Variables

Name	Value	Options
`AI_REVIEWER_GOOGLE_API_KEY`	Gemini API key	Masked
`AI_REVIEWER_GITLAB_TOKEN`	PAT from Step 1	Masked

Step 3: Add a Job¶

.gitlab-ci.yml:

stages:
  - test
  - review

# ... other jobs ...

ai-review:
  stage: review
  image: ghcr.io/konstziv/ai-code-reviewer:1

  script:
    - ai-review

  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

  # Don't block MR if review fails
  allow_failure: true

  # Timeout protection
  timeout: 10m

  # Can be cancelled on new commit
  interruptible: true

  # Don't wait for other stages
  needs: []

  variables:
    AI_REVIEWER_LANGUAGE: uk
    AI_REVIEWER_LANGUAGE_MODE: adaptive

What's Included¶

Feature	Status	Description
Inline discussions		With PAT token
Non-blocking		`allow_failure: true`
Timeout		10 minutes
Interruptible		Cancelled on new commit
Parallel run		`needs: []`
Custom language		`LANGUAGE: uk`

Variations¶

Self-hosted GitLab¶

ai-review:
  # ...
  variables:
    AI_REVIEWER_GITLAB_URL: https://gitlab.mycompany.com

With Custom Docker Registry¶

ai-review:
  # If ghcr.io is not accessible
  image: registry.mycompany.com/devops/ai-code-reviewer:latest

With DEBUG Logs¶

ai-review:
  # ...
  variables:
    AI_REVIEWER_LOG_LEVEL: DEBUG

Only for Specific Branches¶

ai-review:
  # ...
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: always
    - if: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "main"
      when: always

Token Requirements¶

CI_JOB_TOKEN does not work

GitLab's automatic CI_JOB_TOKEN cannot post comments to Merge Requests (the Notes API requires api scope, which CI_JOB_TOKEN does not have).

Use a Personal Access Token (all GitLab plans, including Free) or a Project Access Token (Premium/Ultimate only).

Troubleshooting¶

Review Not Posting Comments¶

Check job logs
Check that your token has scope api
Check that pipeline is running for MR

"401 Unauthorized"¶

Token is invalid or expired. Create a new PAT.

"403 Forbidden"¶

Token doesn't have access to the project. Check permissions.

Full .gitlab-ci.yml Example¶

stages:
  - lint
  - test
  - review
  - deploy

lint:
  stage: lint
  image: python:3.13
  script:
    - pip install ruff
    - ruff check .

test:
  stage: test
  image: python:3.13
  script:
    - pip install pytest
    - pytest

ai-review:
  stage: review
  image: ghcr.io/konstziv/ai-code-reviewer:1
  script:
    - ai-review
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  allow_failure: true
  timeout: 10m
  interruptible: true
  needs: []
  variables:
    AI_REVIEWER_LANGUAGE: uk

deploy:
  stage: deploy
  script:
    - echo "Deploying..."
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Next Step¶

Configuration →