VS Code Extension

Overview

The Koalr VS Code extension surfaces deploy risk scores without leaving your editor. While you are working on a branch, the extension polls Koalr every 60 seconds and displays the current risk score in the VS Code status bar. If the score climbs, you see it before pushing — not after the CI check blocks your PR.

The extension works alongside the GitHub Check Run integration. The Check Run gates merges on GitHub; the extension gives you a continuous in-editor signal during active development.

Requirements

• VS Code 1.85 or later
• A Koalr account on the Growth plan or higher (deploy risk is a paid feature)
• A Koalr API key with the read:prs scope

Installation

Search for Koalr in the VS Code Extensions Marketplace, or install directly:

ext install koalr.koalr-vscode

The extension ID is koalr.koalr-vscode.

After installation, VS Code shows the Koalr status bar item in the bottom bar. It displays Koalr: not configured until you add your API key.

Setup

1. Generate an API key

1. In Koalr, go to Settings → API Keys.
2. Click New API key.
3. Give it a name (e.g., VS Code — your name).
4. Select the read:prs scope.
5. Click Create and copy the key — it is only shown once.

2. Add the key to VS Code

Open the command palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux) and run:

Koalr: Set API Key

Paste your API key when prompted. The key is stored in the OS keychain via VS Code's secrets API — it is never written to settings.json or any file on disk.

Once saved, the status bar updates to show the current branch's risk score (or No PR if no open PR exists for the branch).

Status bar indicator

The status bar item shows one of the following states:

Display	Meaning
Koalr: Low (12)	Open PR found; current risk score is 12 (low risk)
Koalr: Medium (47)	Risk score in the medium range (30–59)
Koalr: High (74)	Risk score in the high range (60–79)
Koalr: Critical (91)	Risk score 80+; deploy risk is elevated
Koalr: No PR	No open pull request found for the current branch
Koalr: not configured	API key has not been set
Koalr: error	Could not reach the Koalr API — hover for details

The score updates automatically every 60 seconds while VS Code is open. Click the status bar item to open the full risk report in your browser.

Risk score thresholds

Range	Label
0–29	Low
30–59	Medium
60–79	High
80–100	Critical

These match the thresholds shown in the Koalr dashboard and the GitHub Check Run. See Deploy Risk for a full explanation of what drives the score.

Manual check

To trigger an immediate score refresh without waiting for the 60-second poll, open the command palette and run:

Koalr: Check PR Risk

This fetches the latest score from the API and updates the status bar immediately.

Configuration

The extension exposes one setting:

Setting	Type	Default	Description
koalr.apiUrl	string	https://api.koalr.com	Koalr API base URL — override for self-hosted deployments

Self-hosted Koalr

If your organization runs a self-hosted Koalr instance, override the API URL in your VS Code settings:

{
  "koalr.apiUrl": "https://koalr.your-company.com"
}

Note: koalr.apiUrl is a machine-scoped setting. It cannot be overridden by workspace settings (.vscode/settings.json) or folder settings. This prevents a malicious repository from redirecting the extension to an attacker-controlled endpoint. Configure it only in your user settings (Cmd+Shift+P → Open User Settings (JSON)).

Security

• API key storage: Your API key is stored using VS Code's context.secrets API, which delegates to the OS keychain (Keychain Access on macOS, Windows Credential Manager, libsecret on Linux). The key is never written to settings.json or any workspace file.
• Machine-scoped URL: The koalr.apiUrl setting is machine-scoped and cannot be set in workspace or folder settings, preventing supply-chain attacks via .vscode/settings.json in a repository.
• Read-only scope: The read:prs scope grants read access to pull request and risk data only. The extension does not write any data back to Koalr.

How it works

The extension calls two Koalr public API endpoints:

1. GET /api/v1/pull-requests?branch=<current-branch> — resolves the open PR for the current branch.
2. GET /api/v1/pull-requests/:id/risk — fetches the risk score and contributing signals for that PR.

Both endpoints require a valid API key in the Authorization: Bearer <key> header. The extension reads the current branch name from the VS Code Git extension — no additional configuration is needed as long as your workspace is a git repository.

Troubleshooting

Status bar shows Koalr: not configured Run Koalr: Set API Key from the command palette and paste your API key.

Status bar shows Koalr: No PR No open pull request was found for the current branch in your Koalr organization. Ensure the PR is open (not draft) and that your GitHub or GitLab integration is active and syncing.

Status bar shows Koalr: error Hover over the status bar item for the specific error message. Common causes:

• The API key has been revoked — generate a new one in Settings → API Keys.
• The koalr.apiUrl setting points to an unreachable host.
• Your Koalr subscription has lapsed — deploy risk requires the Growth plan or higher.

Score not updating The extension polls every 60 seconds. Run Koalr: Check PR Risk for an immediate refresh. If the score is stale after a manual check, confirm the GitHub or GitLab webhook is delivering events to Koalr (check Settings → Integrations → Recent webhook events).

API key prompt does not appear This can happen if VS Code's secret storage is unavailable (common on headless Linux environments). Ensure libsecret is installed: sudo apt-get install libsecret-1-dev on Ubuntu/Debian.