GitHub Copilot

Install secrets-detection hooks, the SonarQube MCP server, SonarQube Agentic Analysis, and Context Augmentation for GitHub Copilot in one command.

Warning: This product is in Beta stage and we may release breaking changes.

sonar integrate copilot configures the SonarQube CLI to work alongside GitHub Copilot. One command sets up:

• A secrets-detection hook that runs before Copilot reads or writes files and blocks any operation that would expose a secret. Because GitHub Copilot CLI doesn't currently support a prompt-time hook, the integration also installs custom instructions that tell the agent to refuse working with exposed tokens.

• The SonarQube MCP server so Copilot can fetch projects, issues, and rules directly.

• SonarQube Agentic Analysis instructions (SonarQube Cloud only, when a project key is available and your organization is entitled) so Copilot can run sonar analyze on your changes.

• A Context Augmentation skill (SonarQube Cloud only, project-level installs only, when enabled for your organization) so Copilot can retrieve project guidelines, architecture, semantic navigation, and dependency context through the CLI integration.

Prerequisites

• The SonarQube CLI is installed and authenticated.

• GitHub Copilot is installed in your editor (or available via the GitHub Copilot CLI).

• You're working inside a project directory (or you're installing globally with --global).

Install

Run inside the project you want to integrate, with the project key:

sonar integrate copilot --project <YourProjectKey>

Or install once for your whole machine:

sonar integrate copilot --global

Warning: --project and --global are mutually exclusive. Passing both causes the command to fail with an "invalid options" error (exit code 2).

Note: Context Augmentation is project-scoped. It's skipped when you run sonar integrate copilot --global; rerun the command without --global from a project directory to install the Context Augmentation skill there.

To configure GitHub Copilot without Context Augmentation, pass --skip-context:

sonar integrate copilot --project <YourProjectKey> --skip-context

What the command does

The integrator runs in three phases:

1. Discovery and validation. It locates your project's config (sonar-project.properties, .sonarlint/connectedMode.json, or the explicit --project flag) and verifies the token.

2. Health check and repair. It calls SonarQube to confirm the token, organization, and project are valid. If the token is broken and you're running interactively, it offers to refresh it.

3. Installation. It writes hooks, MCP config, and (where applicable) Agentic Analysis instructions into either the project directory or your home directory, depending on --global. For eligible project installs, it also installs the Context Augmentation skill unless you pass --skip-context.

Where files are installed

Scope	Hook & instructions location
--global	~/.copilot/ (hooks, settings, instructions)
Project (default)	Inside the repo's Copilot configuration directory
Shared binaries	~/.sonar/sonarqube-cli/bin/ (auxiliary binaries for secrets detection and Context Augmentation)

State for installed integrations is recorded in ~/.sonar/sonarqube-cli/state.json. See State and storage.

Agentic Analysis on global installs

When you run sonar integrate copilot --global, SonarQube's Agentic Analysis instructions are only written if a project key can be resolved (from --project, from your current directory's sonar-project.properties, or from a shared SonarQube for IDE connected mode binding) and your organization is entitled to Agentic Analysis. Otherwise the global install skips the Agentic Analysis portion and only the secrets-detection hook + MCP server are configured.

Restart Copilot

Copilot reads its hook and MCP configuration at startup. Restart Copilot (or your IDE) for the integration to take effect.

Agentic Analysis and Context Augmentation

When you run sonar integrate copilot against a SonarQube Cloud project, the command writes instructions that let GitHub Copilot use SonarQube Cloud's Agentic Analysis and Context Augmentation features.

To enable these features and configure GitHub Copilot to use them effectively, see Make your agent verify its code.

Verify it works

Test the secrets hook

1. Create a file in your project with a fake-looking but secret-shaped value:

   // secrets.js
   const API_KEY = "sqp_1aa323ae0689cd4a1abd062a2ad0a224ae8a1d13";

2. Ask Copilot to read it: "Read secrets.js."

3. Copilot should block the read and explain that the file contains a secret.

Once you've confirmed the hook is active, delete the test file.

Test the MCP server

Ask Copilot to list your SonarQube projects via the MCP server. If the call fails, run sonar auth status to confirm the underlying token is healthy and restart Copilot.

Test Agentic Analysis (SonarQube Cloud only)

In Copilot, ask: "Run sonar analyze --staged and summarize new issues." Copilot should invoke the CLI and report findings. This requires SonarQube Cloud and the Agentic Analysis entitlement on your organization.

Non-interactive install

For provisioning scripts, dotfiles, and onboarding automation:

sonar integrate copilot --global --non-interactive

In non-interactive mode the CLI doesn't prompt for confirmation or token repair. Run sonar auth status afterward to confirm everything is wired up.

Uninstall

The CLI doesn't ship a dedicated uninstall command for integrations yet. To remove the Copilot integration:

1. Delete the hook files written under ~/.copilot/ (global) or in your project's Copilot configuration (project).

2. Remove the SonarQube MCP server entry from your Copilot configuration.

3. Remove the integration entry from ~/.sonar/sonarqube-cli/state.json (under integrations.installed).

See the SonarQube CLI Uninstalling page for the full removal procedure.

Related pages

• Secrets scanning

• Analyzing local changes

• Claude Code

• State and storage

• GitHub Copilot