GitHub Copilot CLI

Install secrets-detection hooks, the SonarQube MCP server, and Sonar Vortex's agentic analysis and context augmentation features for GitHub Copilot CLI with the SonarQube CLI.

sonar integrate copilot configures the SonarQube CLI to work alongside GitHub Copilot CLI. For GitHub Copilot Chat in VS Code, see GitHub Copilot Chat in VS Code. In an interactive terminal, the command prompts you to install each component:

• Secrets detection that runs before GitHub Copilot CLI 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 can also install custom instructions that tell the agent to refuse working with exposed tokens.
• The SonarQube MCP Server so GitHub Copilot CLI can fetch projects, issues, and rules directly.
• Sonar Vortex agentic analysis (SonarQube Cloud only, project-level installs, Team and Enterprise plans) so GitHub Copilot CLI can run sonar analyze on your changes.
• Sonar Vortex context augmentation (SonarQube Cloud only, project-level installs, Team and Enterprise plans) so GitHub Copilot CLI can retrieve project guidelines, architecture, semantic navigation, and dependency context through the CLI integration.

Pass --non-interactive to accept every offered component without prompts (see Non-interactive install).

Prerequisites

• The SonarQube CLI is installed and authenticated.
• GitHub Copilot CLI is installed and available in your terminal.
• 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

Note: In an interactive terminal, if you omit both --global and --project, the CLI asks whether to install for this project or globally before continuing. See Project versus global scope.

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

Note: Agentic analysis is project-scoped. It's skipped when you run sonar integrate copilot --global; rerun the command without --global from a project directory to install agentic analysis instructions for that project.

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 CLI 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, the git origin remote, 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. For each component (secrets hook, prompt-secrets instructions, MCP server, agentic analysis instructions, and context augmentation when eligible), the CLI prompts you to install it, skips it with an explanation, or accepts it automatically in non-interactive mode. Before writing files, it shows a What will be installed summary of accepted features. In interactive mode, press Enter to confirm. Then it installs accepted components into the project directory or your home directory depending on --global.

   Common skip reasons include:

   • A global secrets hook is already configured (the project-level hook is skipped to avoid duplicate scans).
   • Agentic analysis isn't available on your connection (SonarQube Server), your organization isn't entitled, or you used --global (it's project-scoped).
   • Context augmentation isn't available for your organization (requires an eligible SonarQube Cloud plan), you passed --skip-context, or you used --global.

   If global GitHub Copilot CLI instructions already exist and you run a project install, the CLI asks whether you also want a project-local copy of the prompt-secrets instructions.

Where files are installed

Scope	Hook & instructions location
--global	~/.copilot/ (hooks, settings, instructions)
Project (default)	Inside the repo's GitHub Copilot CLI 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.

Restart GitHub Copilot CLI

GitHub Copilot CLI reads its hook and MCP configuration at startup. Restart GitHub Copilot CLI for the integration to take effect.

Sonar Vortex: agentic analysis and context augmentation features

When you run sonar integrate copilot against a SonarQube Cloud project, the command writes instructions that tell GitHub Copilot CLI to run one end-of-turn DEEP sonar analyze agentic --project <key> command covering every file it modified that turn (repeat --file for each path, or fall back to the git change set).

For overviews of these features, see Sonar Vortex agentic analysis and Sonar Vortex context augmentation.

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 GitHub Copilot CLI to read it: "Read secrets.js."
3. GitHub Copilot CLI 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 GitHub Copilot CLI 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 GitHub Copilot CLI.

Test agentic analysis (SonarQube Cloud only)

In GitHub Copilot CLI, ask: "Run sonar analyze --staged and summarize new issues." GitHub Copilot CLI should invoke the SonarQube CLI and report findings. This requires SonarQube Cloud and an agentic analysis entitlement for 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 scope selection, feature selection, install confirmation, token repair, or feature removal. Scope defaults to project when you omit --global, and it installs every component that isn't explicitly skipped. When you authenticate with environment variables, integrate commands also run in non-interactive mode even without the flag. Run sonar auth status afterward to confirm everything is configured correctly.

Uninstall

Run sonar integrate copilot again in an interactive terminal. For each installed feature, the CLI asks Keep? — answer No, confirm Proceed with removal?, and the CLI removes hooks, instructions, and state for that feature. See integrations/README.md for the full flow.

For a manual cleanup or non-interactive environments:

1. Delete the hook files written under ~/.copilot/ (global) or in your project's GitHub Copilot CLI configuration (project).
2. Remove the SonarQube MCP server entry from your GitHub Copilot CLI 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.

GitHub Copilot Chat in VS Code

If you use GitHub Copilot Chat in VS Code rather than GitHub Copilot CLI, sonar integrate copilot still generates useful instruction files; run the command from inside your project directory. It writes an instructions file that Copilot Chat reads automatically, giving it guidance on secrets scanning, issue querying, and SonarQube CLI commands.

One component works differently in Copilot Chat: the pre-tool secrets-scanning hook does not fire. It is wired for the Copilot CLI terminal agent only. The instruction file still tells Copilot Chat to check for secrets, but the check runs as a model instruction rather than an enforced hook.

Copilot Chat in VS Code can also access native SonarQube for VS Code tools available without any CLI setup (#sonarqube_analyzeFile, #sonarqube_getPotentialSecurityIssues, and others). See AI agents in SonarQube for VS Code for details.

Related pages

• Secrets detection

• Analyzing local changes

• Claude Code

• State and storage