GitHub Action

The Technical Debt Radar GitHub Action runs analysis directly in your CI pipeline as a composite action. It is available on the GitHub Marketplace and works alongside or independently of the GitHub App.

Use the Action when you want full control over when and how analysis runs, need to use the outputs in subsequent workflow steps, or prefer CI-based integration over webhook-driven analysis.

Quick Start

Add this to .github/workflows/radar.yml:

name: Technical Debt Radar
on:
  pull_request:
    branches: [main]

jobs:
  radar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: technical-debt-radar/action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          radar-api-key: ${{ secrets.RADAR_API_KEY }}

Inputs

Input	Required	Default	Description
github-token	Yes	---	GitHub token for posting status checks and PR comments. Use ${{ secrets.GITHUB_TOKEN }} for the automatic token.
radar-api-key	Yes	---	Your Radar API key. Store as a repository secret.
fail-on-violations	No	true	Set to false to run analysis without failing the workflow on violations. Useful for initial rollout or advisory mode.
format	No	github	Output format. Options: github (PR comment + status check), json (raw JSON output), text (plain text summary).
include-ai	No	false	Enable AI cross-file analysis. Requires Pro plan. Adds 5--15 seconds to analysis time.
working-directory	No	.	Path to the project root. Set this when your project is in a subdirectory or in monorepo configurations.

Outputs

The action exposes four outputs for use in subsequent workflow steps:

Output	Type	Description
score	number	The debt delta score for the analyzed changes. Lower is better.
violations	number	Total number of violations detected across all categories.
gate-result	string	PASS or FAIL based on your radar.yml policy thresholds.
report-url	string	URL to the full analysis report on the Radar dashboard.

Using Outputs in Subsequent Steps

jobs:
  radar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: technical-debt-radar/action@v1
        id: radar
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          radar-api-key: ${{ secrets.RADAR_API_KEY }}

      - name: Print results
        run: |
          echo "Debt score: ${{ steps.radar.outputs.score }}"
          echo "Violations: ${{ steps.radar.outputs.violations }}"
          echo "Gate: ${{ steps.radar.outputs.gate-result }}"
          echo "Report: ${{ steps.radar.outputs.report-url }}"

      - name: Post to Slack on failure
        if: steps.radar.outputs.gate-result == 'FAIL'
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {
              "text": "Radar gate FAILED on PR #${{ github.event.pull_request.number }} with score ${{ steps.radar.outputs.score }}"
            }

Workflow Examples

Basic Analysis

Run on every pull request targeting main. Blocks the PR if violations exceed thresholds.

name: Technical Debt Radar
on:
  pull_request:
    branches: [main, develop]

jobs:
  radar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: technical-debt-radar/action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          radar-api-key: ${{ secrets.RADAR_API_KEY }}

With AI Analysis

Enable AI cross-file reasoning for deeper analysis. The AI examines the top 10 suspect functions and traces call paths across files to find violations hidden behind abstractions.

name: Technical Debt Radar (with AI)
on:
  pull_request:
    branches: [main]

jobs:
  radar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: technical-debt-radar/action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          radar-api-key: ${{ secrets.RADAR_API_KEY }}
          include-ai: true

Plan requirement: AI analysis requires the Pro plan. On Starter and Solo plans, the include-ai input is ignored.

Matrix Strategy (Multiple Node Versions)

Run analysis across multiple Node.js versions. Useful if your project supports multiple runtimes.

name: Technical Debt Radar (Matrix)
on:
  pull_request:
    branches: [main]

jobs:
  radar:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}

      - uses: technical-debt-radar/action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          radar-api-key: ${{ secrets.RADAR_API_KEY }}

Monorepo Configuration

Analyze multiple packages in a monorepo. Each package has its own radar.yml and runs analysis independently.

name: Technical Debt Radar (Monorepo)
on:
  pull_request:
    branches: [main]

jobs:
  radar:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        package:
          - path: packages/api
            name: API
          - path: packages/auth-service
            name: Auth Service
          - path: packages/order-service
            name: Order Service
    name: Radar - ${{ matrix.package.name }}
    steps:
      - uses: actions/checkout@v4

      - uses: technical-debt-radar/action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          radar-api-key: ${{ secrets.RADAR_API_KEY }}
          working-directory: ${{ matrix.package.path }}

Advisory Mode (No Blocking)

Run analysis and post results without blocking the PR. Useful during initial adoption when you want to observe violations before enforcing.

name: Technical Debt Radar (Advisory)
on:
  pull_request:
    branches: [main]

jobs:
  radar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: technical-debt-radar/action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          radar-api-key: ${{ secrets.RADAR_API_KEY }}
          fail-on-violations: false

Conditional AI Based on PR Size

Enable AI analysis only for larger PRs where cross-file reasoning adds the most value.

name: Technical Debt Radar
on:
  pull_request:
    branches: [main]

jobs:
  radar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Count changed files
        id: changes
        run: |
          COUNT=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | wc -l)
          echo "file-count=$COUNT" >> $GITHUB_OUTPUT

      - uses: technical-debt-radar/action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          radar-api-key: ${{ secrets.RADAR_API_KEY }}
          include-ai: ${{ steps.changes.outputs.file-count > 10 }}

Secrets Configuration

Store your Radar API key as a GitHub repository secret:

1. Go to your repository Settings > Secrets and variables > Actions
2. Click New repository secret
3. Name: RADAR_API_KEY
4. Value: Your API key from the Radar dashboard (Settings > API Keys)

The GITHUB_TOKEN is provided automatically by GitHub Actions. No additional configuration is needed for it.

Action vs. GitHub App

Feature	GitHub Action	GitHub App
Setup	Workflow YAML file	One-click OAuth install
Trigger control	Full control (branches, paths, conditions)	Automatic on all PRs
Output access	Outputs available for subsequent steps	Results via webhook only
Compute	Uses your GitHub Actions minutes	Radar-hosted compute
Monorepo	Matrix strategy per package	Analyzes full PR diff
Offline / self-hosted	Works with self-hosted runners	Requires internet for webhooks

You can use both simultaneously. The GitHub App provides instant webhook-driven analysis, while the Action gives you pipeline control and composable outputs.