GitHub App

The Technical Debt Radar GitHub App connects directly to your GitHub repositories. Every time a pull request is opened or updated, Radar analyzes the changed files and posts results as a status check and PR comment --- blocking the merge if violations exceed your policy thresholds.

Prerequisites

• A Technical Debt Radar account (Solo plan or higher)
• Admin access to the GitHub organization or repository you want to install on
• A radar.yml configuration file in your repository root

Installation

Step 1: Start the OAuth Flow

Navigate to Settings > Integrations in the Radar dashboard and click Install GitHub App. This initiates the GitHub OAuth installation flow.

You will be redirected to GitHub where you can choose which organization and repositories to grant access to.

Step 2: Select Repositories

You can grant access to:

• All repositories in the organization
• Specific repositories you select

Tip: Start with a single repository to validate your radar.yml configuration before rolling out across the organization.

Step 3: Authorize Permissions

The GitHub App requests the following permissions:

Permission	Access	Why It Is Needed
Contents	Read	Read source files for AST analysis
Pull requests	Write	Post violation comments on PRs
Checks	Write	Create status checks (pass/fail)
Statuses	Write	Set commit statuses for merge gating

Radar does not request write access to your code. It never pushes commits, modifies branches, or changes repository settings.

Step 4: Confirm Installation

After authorizing, you are redirected back to the Radar dashboard. The integration status shows Connected with the list of repositories Radar is monitoring.

Webhook Configuration

The GitHub App listens for the following webhook events:

Event	Trigger	Radar Action
pull_request.opened	New PR created	Full analysis of changed files
pull_request.synchronize	New commits pushed to PR	Re-analysis with updated diff
pull_request.reopened	Closed PR reopened	Re-analysis

Webhook payloads are verified using the app's webhook secret. Invalid signatures are rejected with a 401 response.

How Status Checks Work

When Radar finishes analyzing a PR, it creates a commit status check on the head commit:

Pass (green checkmark):

Technical Debt Radar - Gate: PASS
Debt score: 4 | 2 warnings | 0 blocking violations

Fail (red X):

Technical Debt Radar - Gate: FAIL
Debt score: 23 | 3 critical violations blocking merge

The status check links to the full report on the Radar dashboard. When the gate result is FAIL, the PR cannot be merged if your repository has branch protection rules requiring the Radar status check to pass.

Enabling Required Status Checks

To enforce merge blocking:

1. Go to your repository Settings > Branches > Branch protection rules
2. Edit (or create) the rule for your default branch
3. Enable Require status checks to pass before merging
4. Search for Technical Debt Radar and select it
5. Save changes

Once enabled, GitHub will physically prevent merging any PR where Radar reports a FAIL gate result.

PR Comments

On every analysis, Radar posts (or updates) a comment on the pull request with the top violations. The comment includes:

Comment structure:

1. Gate result --- PASS or FAIL with the debt delta score
2. Summary table --- violation counts by category (Architecture, Runtime Risk, Performance, Reliability, Maintainability)
3. Top 5 violations --- each with file path, line number, rule ID, severity, and a plain-language explanation of why it matters
4. Fix instructions --- concrete steps to resolve each violation

## Technical Debt Radar - FAIL

**Debt delta: +23** (threshold: 15) | 3 critical | 2 warnings

| Category | Critical | Warning | Info |
|----------|----------|---------|------|
| Architecture | 1 | 0 | 0 |
| Runtime Risk | 1 | 1 | 0 |
| Performance | 1 | 0 | 0 |
| Reliability | 0 | 1 | 0 |

### Top Violations

1. **`src/orders/domain/order.service.ts:14`** - `layer-boundary-violation` (Critical)
   Domain layer imports `@prisma/client` directly. Move database access to the infrastructure layer.

2. **`src/api/controllers/export.controller.ts:28`** - `sync-fs-in-handler` (Critical)
   `fs.readFileSync` inside a GET handler blocks the event loop. Use `fs.promises.readFile` instead.
...

Radar updates the same comment on subsequent pushes rather than creating new comments, keeping the PR conversation clean.

Plan requirement: Status checks are available on the Solo plan and above. AI-enhanced PR comments with cross-file reasoning and contextual explanations require the Pro plan.

AI-Enhanced PR Comments (Pro Plan)

With AI analysis enabled, PR comments include additional context from Claude:

• Cross-file reasoning --- traces call paths to find violations hidden behind abstractions
• Contextual explanations --- explains why a pattern is dangerous in your specific codebase
• Fix suggestions --- AI-generated code snippets showing how to resolve each violation

AI analysis adds 5--15 seconds to the analysis time but never changes the gate decision. The deterministic analyzers control pass/fail; AI adds advisory context.

Managing the Installation

Viewing Connected Repositories

Go to Settings > Integrations in the Radar dashboard to see all connected repositories, their last analysis time, and current status.

Adding or Removing Repositories

Click Configure next to the GitHub App integration. You will be redirected to GitHub's app settings page where you can modify repository access.

Uninstalling

To remove the GitHub App entirely:

1. Go to your GitHub organization Settings > GitHub Apps > Installed GitHub Apps
2. Click Configure next to Technical Debt Radar
3. Click Uninstall

This stops all webhook events and removes status checks from future PRs. Historical analysis data remains available in the Radar dashboard.

Troubleshooting

Status Check Not Appearing

• Verify the GitHub App is installed on the repository (check Settings > Integrations in the Radar dashboard)
• Confirm the repository has a radar.yml file in the root directory
• Check that the PR modifies TypeScript or JavaScript files --- Radar skips PRs with no analyzable files
• Check the webhook delivery log in GitHub (Settings > GitHub Apps > Advanced > Recent Deliveries)

Status Check Shows "Pending" Indefinitely

• The analysis queue may be backed up. Typical analysis completes in under 30 seconds.
• Check the Radar status page for any ongoing incidents
• Verify your API key is valid in Settings > API Keys

PR Comment Not Posting

• Ensure the GitHub App has pull_requests:write permission
• Check that PR comments are enabled in your project settings (they are on by default)
• On the Starter plan, PR comments show deterministic results only. AI-enhanced comments require Pro.

"Permission Denied" Errors

• The repository owner may have restricted GitHub App installations. Contact your organization admin.
• Re-authorize the app by visiting Settings > Integrations and clicking Reconnect

Webhook Delivery Failures

• GitHub retries failed webhook deliveries automatically
• Check for 4xx or 5xx responses in the GitHub webhook delivery log
• If deliveries consistently fail, verify that your Radar account is active and your subscription is current