GitLab CI Integration

Technical Debt Radar integrates with GitLab to analyze merge requests, post violation comments, and set pipeline status. The integration supports both GitLab.com (SaaS) and self-hosted GitLab instances.

Plan requirement: GitLab integration requires the Pro plan or higher.

Overview

The GitLab integration provides:

• MR comments --- violation summaries posted directly on merge requests
• Pipeline status --- pass/fail status based on your radar.yml policy
• Self-hosted support --- works with any GitLab instance accessible from Radar's infrastructure (or via self-hosted runners)

Setup

Step 1: Create a GitLab Access Token

Create a project or group access token with the following scopes:

Scope	Why It Is Needed
api	Post comments on merge requests and set pipeline status
read_repository	Read source files for analysis

For a project token:

1. Go to your project Settings > Access Tokens
2. Create a token with api and read_repository scopes
3. Set the role to Developer or higher
4. Copy the token value

For a group token (recommended for multiple repositories):

1. Go to your group Settings > Access Tokens
2. Create a token with api and read_repository scopes
3. Set the role to Developer or higher
4. Copy the token value

Step 2: Configure Radar

Add your GitLab credentials in the Radar dashboard:

1. Go to Settings > Integrations > GitLab
2. Enter your GitLab instance URL (e.g., https://gitlab.com or https://gitlab.yourcompany.com)
3. Paste the access token
4. Select the projects to monitor
5. Click Save

Step 3: Add CI Pipeline Configuration

Add the Radar analysis stage to your .gitlab-ci.yml:

stages:
  - test
  - radar

radar-scan:
  stage: radar
  image: node:20-alpine
  variables:
    RADAR_API_KEY: $RADAR_API_KEY
    RADAR_GITLAB_TOKEN: $GITLAB_ACCESS_TOKEN
    RADAR_GITLAB_URL: $CI_SERVER_URL
    RADAR_PROJECT_ID: $CI_PROJECT_ID
    RADAR_MR_IID: $CI_MERGE_REQUEST_IID
  script:
    - npx @radar/cli scan --format gitlab
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  allow_failure: false

Step 4: Set CI/CD Variables

Add the following variables in Settings > CI/CD > Variables:

Variable	Value	Protected	Masked
RADAR_API_KEY	Your Radar API key	Yes	Yes
GITLAB_ACCESS_TOKEN	The access token from Step 1	Yes	Yes

Environment Variables

The Radar CLI uses these environment variables when running in GitLab CI:

Variable	Source	Description
RADAR_API_KEY	CI/CD variable	Authenticates with the Radar API
RADAR_GITLAB_TOKEN	CI/CD variable	Authenticates with the GitLab API for posting MR comments
RADAR_GITLAB_URL	$CI_SERVER_URL (automatic)	GitLab instance URL
RADAR_PROJECT_ID	$CI_PROJECT_ID (automatic)	Numeric project ID
RADAR_MR_IID	$CI_MERGE_REQUEST_IID (automatic)	Merge request internal ID
CI_COMMIT_SHA	Automatic	Commit SHA for status reporting

Pipeline Examples

Basic MR Analysis

Runs on every merge request. Fails the pipeline if violations exceed thresholds.

radar-scan:
  stage: radar
  image: node:20-alpine
  variables:
    RADAR_API_KEY: $RADAR_API_KEY
    RADAR_GITLAB_TOKEN: $GITLAB_ACCESS_TOKEN
  script:
    - npx @radar/cli scan --format gitlab
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

With AI Analysis

Enable AI cross-file reasoning for deeper analysis.

radar-scan:
  stage: radar
  image: node:20-alpine
  variables:
    RADAR_API_KEY: $RADAR_API_KEY
    RADAR_GITLAB_TOKEN: $GITLAB_ACCESS_TOKEN
  script:
    - npx @radar/cli scan --format gitlab --include-ai
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Advisory Mode (Non-Blocking)

Run analysis and post MR comments without blocking the pipeline. Useful during initial rollout.

radar-scan:
  stage: radar
  image: node:20-alpine
  variables:
    RADAR_API_KEY: $RADAR_API_KEY
    RADAR_GITLAB_TOKEN: $GITLAB_ACCESS_TOKEN
  script:
    - npx @radar/cli scan --format gitlab --no-fail
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  allow_failure: true

Monorepo with Parallel Jobs

Analyze multiple packages in parallel using GitLab's parallel:matrix feature.

radar-scan:
  stage: radar
  image: node:20-alpine
  variables:
    RADAR_API_KEY: $RADAR_API_KEY
    RADAR_GITLAB_TOKEN: $GITLAB_ACCESS_TOKEN
  parallel:
    matrix:
      - PACKAGE_DIR:
          - packages/api
          - packages/auth-service
          - packages/order-service
  script:
    - npx @radar/cli scan --format gitlab --working-directory $PACKAGE_DIR
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Caching Node Modules

Speed up analysis by caching the Radar CLI installation between pipeline runs.

radar-scan:
  stage: radar
  image: node:20-alpine
  cache:
    key: radar-cli
    paths:
      - node_modules/
  variables:
    RADAR_API_KEY: $RADAR_API_KEY
    RADAR_GITLAB_TOKEN: $GITLAB_ACCESS_TOKEN
  before_script:
    - npm install @radar/cli
  script:
    - npx @radar/cli scan --format gitlab
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

MR Comment Format

When analysis completes, Radar posts a comment on the merge request with the same structure as GitHub PR comments:

1. Gate result --- PASS or FAIL with the debt delta score
2. Violation summary --- counts by category and severity
3. Top violations --- file path, line number, rule ID, explanation, and fix steps

On subsequent pushes to the same MR, Radar updates the existing comment rather than creating a new one.

Self-Hosted GitLab

For self-hosted GitLab instances, additional configuration is needed:

Network Access

Radar's hosted infrastructure must be able to reach your GitLab instance. Options:

1. Allow-list Radar's IP addresses --- contact support for the current IP range
2. Use a self-hosted runner --- run the Radar CLI on a runner inside your network that can reach both GitLab and the Radar API

TLS Certificates

If your GitLab instance uses a self-signed certificate or a private CA:

radar-scan:
  stage: radar
  image: node:20-alpine
  variables:
    RADAR_API_KEY: $RADAR_API_KEY
    RADAR_GITLAB_TOKEN: $GITLAB_ACCESS_TOKEN
    NODE_EXTRA_CA_CERTS: /path/to/ca-bundle.crt
  script:
    - npx @radar/cli scan --format gitlab
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Custom Instance URL

Set RADAR_GITLAB_URL explicitly if the $CI_SERVER_URL variable does not resolve correctly:

variables:
  RADAR_GITLAB_URL: https://gitlab.yourcompany.com

Troubleshooting

MR Comment Not Appearing

• Verify the access token has api scope
• Check that the token is not expired
• Ensure $CI_MERGE_REQUEST_IID is available (the job must run on merge request pipelines, not branch pipelines)

Pipeline Status Not Updating

• The --format gitlab flag is required for pipeline integration. Without it, the CLI outputs to stdout but does not update GitLab status.
• Verify the RADAR_API_KEY is correct and the account is active

"401 Unauthorized" Errors

• The GitLab access token may have expired or been revoked
• For group tokens, verify the project belongs to the group
• For project tokens, verify the token role is Developer or higher

Self-Hosted Connection Issues

• Verify network connectivity between the runner and api.radardebt.dev
• Check firewall rules for outbound HTTPS (port 443)
• If using a proxy, set HTTPS_PROXY in your CI/CD variables