Getting Started

Installation

Install Technical Debt Radar via CLI, GitHub App, GitHub Action, or GitLab CI. Complete setup guides for every integration path.

Installation

Radar supports four installation paths. Choose the one that fits your workflow:

Path	Best For	Setup Time
CLI	Local development, manual scans, AI fix loop	1 minute
GitHub App	Automatic PR analysis with dashboard	3 minutes
GitHub Action	CI/CD pipeline enforcement	5 minutes
GitLab CI	GitLab merge request analysis	5 minutes

You can use multiple paths simultaneously --- run the CLI locally during development, and enforce with the GitHub Action on every PR.

CLI

The CLI is the fastest way to start. It runs entirely on your machine with zero external dependencies.

Install Globally

npm install -g @radar/cli

Verify:

radar --version

Run Without Installing

npx @radar/cli scan .

Tip: Using npx always runs the latest version. Use the global install if you want consistent versions across your team or faster startup.

Initialize Your Project

radar init

This auto-detects your framework, ORM, layer structure, module boundaries, architecture pattern, and data volumes. It generates two files:

radar.yml --- Project configuration (stack, layers, modules, volumes)
rules.yml --- Enforcement rules (auto-generated from your detected architecture preset)

Run a Scan

radar scan .

Enable AI Features

Set your Anthropic API key to enable AI-powered summaries, cross-file analysis, and fix generation:

export ANTHROPIC_API_KEY=sk-ant-api03-...

Then use AI features:

radar scan . --format ai-prompt  # Generate AI-friendly report
radar fix .                       # AI-powered auto-fix
radar summary                     # AI executive summary

Note: AI features are optional. All violation detection is deterministic and runs without an API key. AI adds contextual explanations and fix suggestions on top of the deterministic findings.

CLI Reference

Command	Description
`radar init`	Auto-detect stack, generate config files
`radar scan <path>`	Scan and report violations
`radar fix <path>`	AI auto-fix (requires `ANTHROPIC_API_KEY`)
`radar gate`	Gate evaluation for CI (exit code 0 or 1)
`radar badge`	Generate architecture health badge
`radar pack list`	List available rule packs
`radar pack info <name>`	Show rule pack details
`radar pack install <name>`	Install a rule pack
`radar summary`	AI executive summary

GitHub App

The GitHub App provides the full experience: automatic PR analysis, inline comments, status checks, and the web dashboard.

Step 1: Install the App

Go to github.com/apps/technical-debt-radar
Click Install
Select the organization or account
Choose which repositories to grant access to:
- All repositories --- Radar analyzes every repo
- Only select repositories --- Choose specific repos

Step 2: Permissions

The GitHub App requires these permissions:

Permission	Level	Why
Pull requests	Read & Write	Post scan results as PR comments, update status checks
Contents	Read	Read source files and config (`radar.yml`, `rules.yml`)
Checks	Read & Write	Create pass/fail check runs on PRs
Metadata	Read	List repositories and basic repo info

The app receives webhook events for pull_request (opened, synchronize, reopened) only. It does not access issues, releases, or other repository data.

Step 3: Add Configuration

After installing the app, add radar.yml to each repository you want to analyze. The fastest way:

cd your-project
npx @radar/cli init
git add radar.yml rules.yml
git commit -m "Add Radar configuration"
git push

Step 4: Open a PR

Open any pull request. Within 30 seconds, Radar posts a comment with the scan results and sets a status check:

Pass --- Green check, merge allowed
Fail --- Red X, merge blocked until violations are fixed

What You Get

Automatic scan on every PR (opened, updated, reopened)
PR comment with categorized violations, debt score, and gate result
GitHub status check that blocks merge when violations exceed thresholds
Web dashboard with trends, hotspots, and violation history

Note: The GitHub App requires no workflow files or CI configuration. Once installed, it works automatically on every PR that has a radar.yml in the repository root.

GitHub Action

The GitHub Action runs Radar as a step in your CI/CD pipeline. Use this when you want full control over when and how Radar runs, or when you cannot install the GitHub App.

Basic Setup

Create .github/workflows/radar.yml:

name: Technical Debt Radar
on:
  pull_request:
    branches: [main, develop]
    paths:
      - 'src/**'
      - '*.ts'
      - '*.js'
      - 'radar.yml'
      - 'rules.yml'

permissions:
  pull-requests: write
  contents: read

jobs:
  radar-scan:
    name: Radar Scan
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Run Technical Debt Radar
        id: radar
        uses: technical-debt-radar/action@v1
        with:
          fail-on: critical
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Check Results
        if: always()
        run: |
          echo "Violations: ${{ steps.radar.outputs.total-violations }}"
          echo "Blocking: ${{ steps.radar.outputs.blocking-violations }}"
          echo "Score: ${{ steps.radar.outputs.debt-score }}"
          echo "Gate: ${{ steps.radar.outputs.gate-result }}"

With AI Features

To enable AI-powered analysis summaries and cross-file reasoning, add your Anthropic API key:

name: Technical Debt Radar (AI)
on:
  pull_request:
    branches: [main, develop]
    paths:
      - 'src/**'
      - '*.ts'
      - '*.js'
      - 'radar.yml'
      - 'rules.yml'

permissions:
  pull-requests: write
  contents: read

jobs:
  radar-scan:
    name: Radar Scan with AI
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Run Technical Debt Radar
        id: radar
        uses: technical-debt-radar/action@v1
        with:
          fail-on: critical
          ai: true
          post-comment: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Check Results
        if: always()
        run: |
          echo "Violations: ${{ steps.radar.outputs.total-violations }}"
          echo "Blocking: ${{ steps.radar.outputs.blocking-violations }}"
          echo "Score: ${{ steps.radar.outputs.debt-score }}"
          echo "Gate: ${{ steps.radar.outputs.gate-result }}"

Warning: Never hardcode your ANTHROPIC_API_KEY in the workflow file. Always use GitHub Secrets. Go to your repository Settings > Secrets and variables > Actions > New repository secret.

Action Inputs

Input	Required	Default	Description
`config`	No	`radar.yml`	Path to your Radar configuration file
`rules`	No	`rules.yml`	Path to your rules file
`fail-on`	No	`critical`	When to fail the check: `critical`, `warning`, or `none`
`ai`	No	`false`	Enable AI features (scan summary, cross-file analysis)
`post-comment`	No	`true`	Post scan results as a PR comment
`node-version`	No	`20`	Node.js version to use

Action Outputs

Output	Description	Example
`total-violations`	Total number of violations found	`12`
`blocking-violations`	Number of blocking violations	`3`
`debt-score`	Calculated debt score	`38`
`gate-result`	Gate decision	`pass` or `fail`

Using Outputs in Subsequent Steps

You can use Radar outputs to drive downstream logic:

- name: Run Technical Debt Radar
  id: radar
  uses: technical-debt-radar/action@v1
  with:
    fail-on: critical
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

- name: Notify Slack on High Debt
  if: steps.radar.outputs.debt-score > 50
  run: |
    curl -X POST ${{ secrets.SLACK_WEBHOOK }} \
      -H 'Content-Type: application/json' \
      -d '{"text": "Radar: debt score ${{ steps.radar.outputs.debt-score }} on PR #${{ github.event.pull_request.number }}"}'

- name: Block on Any Violation
  if: steps.radar.outputs.total-violations > 0
  run: exit 1

Monorepo Setup

For monorepos with multiple packages, run Radar on specific paths:

jobs:
  radar-api:
    name: Radar — API
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: technical-debt-radar/action@v1
        with:
          config: apps/api/radar.yml
          rules: apps/api/rules.yml
          fail-on: critical
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  radar-web:
    name: Radar — Web
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: technical-debt-radar/action@v1
        with:
          config: apps/web/radar.yml
          rules: apps/web/rules.yml
          fail-on: warning
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitLab CI

Radar works in GitLab CI/CD pipelines using the CLI. Add a stage to your .gitlab-ci.yml:

Basic Setup

# .gitlab-ci.yml
stages:
  - test
  - quality

radar-scan:
  stage: quality
  image: node:20-alpine
  before_script:
    - npm install -g @radar/cli
  script:
    - |
      if [ ! -f "radar.yml" ]; then
        radar init --no-ai --path .
      fi
    - radar scan . --format json > radar-report.json
    - |
      GATE=$(cat radar-report.json | jq -r '.gateResult // "pass"')
      BLOCKING=$(cat radar-report.json | jq -r '.stats.blockingViolations // 0')
      SCORE=$(cat radar-report.json | jq -r '.stats.debtScore // 0')
      echo "Gate: $GATE | Blocking: $BLOCKING | Score: $SCORE"
      if [ "$GATE" = "fail" ]; then
        echo "Radar: $BLOCKING blocking violations found. Merge blocked."
        radar scan . --format text
        exit 1
      fi
  artifacts:
    when: always
    paths:
      - radar-report.json
    expire_in: 30 days
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

With AI Features

radar-scan:
  stage: quality
  image: node:20-alpine
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
  before_script:
    - npm install -g @radar/cli
  script:
    - radar scan . --format text
    - radar scan . --format json > radar-report.json
    - |
      GATE=$(cat radar-report.json | jq -r '.gateResult // "pass"')
      if [ "$GATE" = "fail" ]; then
        exit 1
      fi
  artifacts:
    when: always
    paths:
      - radar-report.json
    expire_in: 30 days
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

Tip: Store your ANTHROPIC_API_KEY in GitLab CI/CD Variables (Settings > CI/CD > Variables) with the Masked and Protected flags enabled.

GitLab MR Comment

To post scan results as a merge request comment, add this after the scan step:

radar-comment:
  stage: quality
  image: node:20-alpine
  needs: [radar-scan]
  script:
    - |
      COMMENT=$(radar scan . --format pr)
      curl --request POST \
        --header "PRIVATE-TOKEN: ${GITLAB_API_TOKEN}" \
        --header "Content-Type: application/json" \
        --data "{\"body\": $(echo "$COMMENT" | jq -Rs .)}" \
        "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/merge_requests/${CI_MERGE_REQUEST_IID}/notes"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

Note: Create a GitLab Personal Access Token or Project Access Token with api scope and store it as the GITLAB_API_TOKEN CI/CD variable.

Verifying Your Installation

Regardless of which path you chose, verify that Radar is working:

# Check that config was generated correctly
radar scan . --format json | jq '.stats'

{
  "totalViolations": 12,
  "blockingViolations": 7,
  "warningViolations": 5,
  "debtScore": 58,
  "filesScanned": 47,
  "scanDuration": "2.3s"
}

If you see scan results, Radar is working. The number of violations does not matter at this stage --- see Your First Scan for how to interpret and reduce your initial report.

Next Steps

Quickstart --- Walk through the full flow from install to passing gate.
Your First Scan --- Understand every section of the scan report.
Configuration --- Customize radar.yml and rules.yml.

Previous← Quickstart NextYour First Scan →

Technical Debt Radar Documentation