Automating Code Review in GitLab CI: A Complete Setup Guide

GitLab's CI/CD pipeline and merge request system have a few structural differences from GitHub's PR model that affect how automated code review is wired in. This guide covers the complete configuration — MR-level triggers, repository scope, and the noise-reduction settings that most teams need before automated review is useful in daily workflow.

This guide assumes you've already connected your GitLab repository to Replixa via the dashboard or CLI. If you haven't, start with the quickstart guide first.

GitLab CI vs. GitHub Actions: what's different

The core behavioral differences that affect this integration:

• Pipeline triggers: GitLab uses rules or only/except syntax in the pipeline YAML to control when jobs run. Merge request event filtering works differently from GitHub's workflow trigger model.
• Token authentication: GitLab supports project-level and group-level CI/CD variables. Group variables are the efficient choice for multi-project organizations.
• MR vs. PR terminology: GitLab calls them merge requests (MRs). Replixa's GitLab integration uses the GitLab API's MR endpoints natively — the Replixa action handles the translation, but the terminology in your CI logs will reflect GitLab's model.
• Review posting: Replixa posts suggestions to GitLab MR discussions using the Suggestions API (the same API that powers native GitLab inline suggestions). One-click apply works natively in the GitLab MR UI.

Step 1: Set up the API token as a CI variable

Generate a Replixa API token in your dashboard at Settings → API Tokens. The token needs review:write and config:read scopes.

In GitLab, navigate to your project (or group, for shared org-wide configuration) → Settings → CI/CD → Variables. Add:

Key:   REPLIXA_API_TOKEN
Value: <your token>
Type:  Variable (masked)
Protected: Yes (if you only want it available on protected branches)
Masked: Yes

Setting "Masked" ensures the token value doesn't appear in CI job logs. Setting "Protected" restricts the variable to pipelines running on protected branches — recommended for most configurations, but check that your default branch and any target branches for MRs are marked as protected in GitLab's Branch settings.

Step 2: Add the Replixa job to your .gitlab-ci.yml

stages:
  - test
  - review   # Add review as a separate stage after tests

# ... your existing test jobs ...

replixa-review:
  stage: review
  image: replixa/review-runner:latest
  variables:
    GIT_DEPTH: 0   # Required: full clone for style graph diff
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - replixa review
        --token "$REPLIXA_API_TOKEN"
        --project "$CI_PROJECT_PATH"
        --mr-iid "$CI_MERGE_REQUEST_IID"
        --base-sha "$CI_MERGE_REQUEST_DIFF_BASE_SHA"
        --head-sha "$CI_COMMIT_SHA"
  allow_failure: true  # Review findings don't block merge by default

A few notes:

• GIT_DEPTH: 0 is required for the same reason as in GitHub Actions — style graph construction needs the full commit history on the base branch to build accurate pattern data.
• allow_failure: true means Replixa findings will post as suggestions but won't cause the pipeline to fail or block the MR. If you want Replixa to block merges on specific finding types (e.g., security patterns), this can be set to false and thresholds configured in replixa.yml.
• The if: $CI_PIPELINE_SOURCE == "merge_request_event" rule ensures the job only runs on MR pipelines, not on branch pushes or scheduled pipelines.

Step 3: Configure review scope with replixa.yml

Drop a replixa.yml at the repository root to configure which paths are reviewed and with what settings:

# replixa.yml
version: 2

review:
  include:
    - "app/**"
    - "lib/**"
    - "spec/**"   # Include test files in style review

  exclude:
    - "vendor/**"
    - "node_modules/**"
    - "**/*.generated.rb"
    - "db/schema.rb"   # Generated schema file

  suggestion_threshold: 0.75
  format: inline_patch

  # For GitLab, MR discussions are posted as native GitLab Suggestions
  # (same format as the "Suggest changes" feature in the GitLab MR UI)
  gitlab_native_suggestions: true

The gitlab_native_suggestions: true setting is GitLab-specific. It formats Replixa's inline patches using GitLab's native Suggestion markdown syntax, which means authors can apply them using the standard GitLab "Apply suggestion" button without any additional tooling. If set to false, Replixa posts as standard discussion threads with the suggested change in a code block.

Step 4: Suppressing noise on non-blocking style issues

One common configuration problem after initial setup: Replixa posts suggestions on issues that the team has decided to deprioritize — formatting preferences, minor naming variations, or patterns that are intentionally inconsistent in certain parts of the codebase. This creates noise and trains engineers to dismiss suggestions, which undermines the value of the integration.

There are three ways to suppress specific categories:

Path-level exclusion

Add the path to the exclude list in replixa.yml. This completely stops review for that path. Use for generated files, vendored code, legacy modules undergoing active replacement, or test fixtures.

Category suppression

# replixa.yml
review:
  suppress_categories:
    - naming_case    # Ignore camelCase vs snake_case inconsistencies
    - import_order   # Ignore import ordering (handled by formatter)
    - comment_style  # Ignore comment format variations

Category suppression prevents Replixa from posting suggestions in those finding categories, regardless of confidence score.

Threshold by file type

# replixa.yml
review:
  file_type_overrides:
    "*.rb":
      suggestion_threshold: 0.80   # Higher bar for Ruby files
    "*.yml":
      suggestion_threshold: 0.90   # Very high bar for config files
    "*.ts":
      suggestion_threshold: 0.70   # Lower threshold for TypeScript

Handling merge trains and fast-forward merges

If your GitLab configuration uses merge trains or requires fast-forward merges, the Replixa job runs correctly — it uses the MR's diff base SHA rather than the current branch HEAD, so it's stable against rebase operations that happen during merge train processing. No special configuration is needed.

For repositories that rebase MR branches before merge (rather than merge commits), make sure GIT_DEPTH: 0 is set. A shallow clone may not include the full base branch history needed to resolve the diff base SHA accurately after a rebase.

First two weeks: calibrating the signal

The initial calibration period is the same as for GitHub Actions: watch suggestion acceptance rate in the Replixa dashboard. A rate below 50% suggests the threshold is too low. A rate above 85% in the first two weeks suggests it's too high — you may be suppressing genuinely useful findings.

One GitLab-specific note: if your organization uses protected branches with approval rules, Replixa's allow_failure: true setting ensures the review job doesn't interfere with your approval gate count. Replixa is additive — it posts suggestions without modifying your existing approval requirements. If you later want to require Replixa's security findings to be resolved before merge, that's configured in GitLab's MR approval settings as an external status check, not through allow_failure.