> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-cli/integrations/github-copilot-cli.md).

# GitHub Copilot CLI

Install secrets-detection hooks, the SonarQube MCP Server, and Vortex analysis and Vortex context 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](#github-copilot-chat-in-vs-code). In an interactive terminal, the command shows these recommended components, then asks you to install them or customize the selection (see [Install confirmation](https://docs.sonarsource.com/sonarqube-cli/integrations/integrations.md#install-confirmation)):

* [Secrets detection](https://docs.sonarsource.com/sonarqube-cli/analysis/secrets-detection.md): a pre-tool-use hook that blocks a file read that would expose a secret, and a prompt hook that redacts secrets in the prompt before the model sees it. When a secret cannot be redacted, or the scan cannot run, the prompt hook replaces the prompt with a blocking notice and does not send the original text.
* [The SonarQube MCP Server](https://docs.sonarsource.com/sonarqube-mcp-server/), which lets GitHub Copilot CLI fetch projects, issues, and rules directly.
* Sonar Vortex (when your connection has a Vortex subscription: SonarQube Cloud Team (annual) or Enterprise plan, or SonarQube Server 2026.5 or newer Enterprise and Data Center editions): installs Vortex analysis and Vortex context together. It adds:
  * [Vortex analysis](https://docs.sonarsource.com/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-analysis.md) instructions that tell GitHub Copilot CLI to run `sonar analyze agentic` on your changes at end of turn
  * `sessionStart` and `subagentStart` hooks that inject [Vortex context](https://docs.sonarsource.com/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-context.md) when a session starts, giving GitHub Copilot CLI access to project guidelines, architecture, semantic navigation, and dependency context

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

## Prerequisites

* [The SonarQube CLI is installed and authenticated](https://docs.sonarsource.com/sonarqube-cli/quickstart-guide.md).
* GitHub Copilot CLI is installed and available in your terminal.

## Install

Install once for this machine:

```bash
sonar integrate copilot
```

The command writes hooks and config to `~/.copilot/` and applies to every GitHub Copilot CLI session on this machine. See [Project versus global scope](https://docs.sonarsource.com/sonarqube-cli/integrations/integrations.md#project-versus-global-scope).

### What the command does

The integrator runs in two phases:

1. Validation. It checks that your saved token can reach SonarQube. On SonarQube Cloud, your connection must include an organization. An invalid token stops setup and tells you to run `sonar auth login`. An unreachable server stops setup and asks you to check the server URL and your network connection.
2. Installation. The CLI shows a [What will be installed](https://docs.sonarsource.com/sonarqube-cli/integrations/integrations.md#install-confirmation) summary of the recommended components (secrets detection, MCP server, and Vortex when eligible). In an interactive terminal, choose **Install recommended** to write that set, or **Customize** to accept or decline each component and then press Enter. Components that are not available are skipped with an explanation. In non-interactive mode, every eligible component is installed without prompts. The CLI then writes the accepted components into `~/.copilot/`.

   Common skip reasons include:

   * Your connection does not have a Vortex subscription (only available with SonarQube Cloud Team (annual) or Enterprise plan, or SonarQube Server 2026.5 or newer Enterprise and Data Center editions).

### Options

| Option              | Description                                                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `--non-interactive` | Non-interactive mode (no prompts).                                                                                                 |
| `--global`, `-g`    | Deprecated since 1.9.0. The install is already global; using the flag prints a warning and does not change the installation scope. |

### Where files are installed

| Location        | Hook and instructions location                                                              |
| --------------- | ------------------------------------------------------------------------------------------- |
| User home       | `~/.copilot/` (hooks, settings, instructions)                                               |
| Shared binaries | `~/.sonar/sonarqube-cli/bin/` (auxiliary binaries for secrets detection and Vortex context) |

State for installed integrations is recorded in `~/.sonar/sonarqube-cli/state.json`. See [State and storage](https://docs.sonarsource.com/sonarqube-cli/administration/state-and-storage.md).

### Prompt hook

The prompt hook is a `userPromptTransformed` hook under `~/.copilot/hooks/`. It scans the prompt before GitHub Copilot CLI sends it to the model.

* A prompt with no secrets is left unchanged.
* Secrets that can be redacted are replaced in the prompt, and the message is still sent. The prompt then ends with `[SonarQube] Secrets were redacted from this message. Let the user know that SonarQube redacted them.`
* When a secret cannot be redacted, or the scan cannot run, the hook replaces the whole prompt with a notice that starts with `[SonarQube] Message blocked:`. The notice says the original content was not sent and asks Copilot to tell you that SonarQube blocked the message. A missing login tells you to run `sonar auth login`. A missing analyzer tells you to re-run `sonar integrate`. A failed scan uses the same notice.
* A prompt the hook cannot read is left unchanged.

The CLI does not install prompt-secrets instructions. Upgrading the CLI removes a prompt-secrets block that an earlier install wrote in `~/.copilot/instructions/sonarqube.instructions.md`, between `<!-- sonar:begin:copilot-prompt-secrets -->` and `<!-- sonar:end:copilot-prompt-secrets -->`, and leaves the rest of that file in place, including Vortex instructions. Run `sonar integrate copilot` again to remove that block without waiting for an upgrade.

## 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.

## Vortex analysis and Vortex context

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 `sonar analyze agentic --depth DEEP` command covering every file it modified that turn (repeat `--file` for each path, or fall back to the git change set). Those instructions go in `~/.copilot/instructions/sonarqube.instructions.md`. The instructions omit `--project` because each file is analyzed against the project that owns it. In a repository with several projects, they tell GitHub Copilot CLI to run that command from a directory that contains every file changed in the turn, usually the repository root. Re-run `sonar integrate copilot` so an existing snippet picks up that paragraph. If analysis reports that no project is configured, the instructions tell the agent to stay silent for the rest of the session instead of repeating a skip notice. See [Files and the project root](https://docs.sonarsource.com/sonarqube-cli/analysis/analyzing-local-changes.md#files-and-the-project-root).

It also writes `sessionStart` and `subagentStart` hooks that inject Vortex context when a Copilot session starts. When context cannot load, Copilot asks the agent to tell you once per session. A subagent start does not show that warning. See [When Vortex context does not load](https://docs.sonarsource.com/sonarqube-cli/integrations/integrations.md#when-vortex-context-does-not-load). If a previous install wrote `.github/skills/sonar-context-augmentation/SKILL.md`, update to SonarQube CLI 1.8.0 or newer, then re-run `sonar integrate copilot` to replace that leftover skill with the session-start hooks.

For overviews of these features, see [Vortex analysis](https://docs.sonarsource.com/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-analysis.md) and [Vortex context](https://docs.sonarsource.com/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-context.md).

## Verify it works

### Test the secrets hook

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

   ```javascript
   // 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 prompt hook

Send GitHub Copilot CLI a message that includes the same kind of fake token. The token should be redacted before the model sees the prompt, and the prompt should end with a `[SonarQube]` line that says SonarQube redacted the secrets.

### 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 Vortex analysis

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 a [Sonar Vortex](https://docs.sonarsource.com/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-analysis.md) subscription.

## Non-interactive install

For provisioning scripts, dotfiles, and onboarding automation:

```bash
sonar integrate copilot --non-interactive
```

In non-interactive mode the CLI does not prompt for feature selection, install confirmation, token repair, or feature removal. Every component that's not explicitly skipped is installed automatically. When you authenticate with [environment variables](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/environment-variables.md), integrate commands also run in non-interactive mode even without the flag. Run [`sonar auth status`](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-auth-status) afterward to confirm everything is configured correctly.

## Uninstall

Run `sonar integrate copilot` again in an interactive terminal and choose **Customize**. 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. Vortex is removed as one unit (Vortex analysis instructions and session-start hooks). See [integrations/README.md](https://docs.sonarsource.com/sonarqube-cli/integrations/integrations.md#removing-installed-features) for the full flow.

For a manual cleanup or non-interactive environments:

1. Delete the hook files written under `~/.copilot/`.
2. If an earlier install left a prompt-secrets block in `~/.copilot/instructions/sonarqube.instructions.md`, delete the block between `<!-- sonar:begin:copilot-prompt-secrets -->` and `<!-- sonar:end:copilot-prompt-secrets -->`. Leave any Vortex instructions in that file.
3. Remove the SonarQube MCP Server entry from your GitHub Copilot CLI configuration.
4. Remove the integration entry from `~/.sonar/sonarqube-cli/state.json` (under `integrations.installed`).

See the SonarQube CLI [Uninstalling](https://docs.sonarsource.com/sonarqube-cli/administration/uninstall.md) 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 writes `~/.copilot/instructions/sonarqube.instructions.md` when Vortex is installed. Copilot Chat can read that file. It holds Vortex analysis instructions.

The pre-tool-use hook and the prompt hook run in GitHub Copilot CLI. They do not run in Copilot Chat, and this integration does not add a prompt-secrets instruction for Copilot Chat.

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](https://docs.sonarsource.com/sonarqube-for-vs-code/ai-capabilities/integrations.md) in SonarQube for VS Code for details.

For the full SonarQube MCP Server integration with Copilot in Agent mode, see [VS Code with GitHub Copilot](https://docs.sonarsource.com/sonarqube-mcp-server/setup/quickstart-guides/vs-code.md) in the MCP server docs.

## Related pages <a href="#related-pages" id="related-pages"></a>

* [Secrets detection](https://docs.sonarsource.com/sonarqube-cli/analysis/secrets-detection.md)
* [Analyzing local changes](https://docs.sonarsource.com/sonarqube-cli/analysis/analyzing-local-changes.md)
* [State and storage](https://docs.sonarsource.com/sonarqube-cli/administration/state-and-storage.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sonarsource.com/sonarqube-cli/integrations/github-copilot-cli.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
