> 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.md).

# GitHub Copilot

`sonar integrate copilot` configures the SonarQube CLI to work alongside [GitHub Copilot](https://docs.github.com/copilot). In an interactive terminal, the command prompts you to install each component:

* **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 can also install 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, project-level installs only, when 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 your organization is entitled on an eligible SonarQube Cloud plan) so Copilot 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](#non-interactive-install)).

## Prerequisites

* [The SonarQube CLI is installed and authenticated](/sonarqube-cli/quickstart-guide.md).
* 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:

```bash
sonar integrate copilot --project <YourProjectKey>
```

Or install once for your whole machine:

```bash
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](/sonarqube-cli/integrations/integrations.md#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 without Context Augmentation, pass `--skip-context`:

```bash
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 when the repository is bound on SonarQube, 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 either prompts you to install it, skips it with an explanation, or installs it automatically in non-interactive mode. Accepted components are written into either 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 Copilot 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 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](/sonarqube-cli/administration/state-and-storage.md).

## 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](/agent-centric-development-cycle/features/agentic-analysis.md) and [Context Augmentation](/agent-centric-development-cycle/features/context-augmentation.md) features.

To enable these features and configure GitHub Copilot to use them effectively, see [Make your agent verify its code](/agent-centric-development-cycle/how-to-guides/verify-your-code/make-your-agent-verify-its-code.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 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:

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

In non-interactive mode the CLI doesn't prompt for scope selection, feature selection, or token repair; scope defaults to project when you omit `--global`, and it installs every component that isn't explicitly skipped. When you authenticate with [environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md), integrate commands also run in non-interactive mode even without the flag. Run [`sonar auth status`](/sonarqube-cli/using-sonarqube-cli/commands.md#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](/sonarqube-cli/administration/uninstall.md) page for the full removal procedure.

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

* [Secrets scanning](/sonarqube-cli/analysis/secrets-scanning.md)
* [Analyzing local changes](/sonarqube-cli/analysis/analyzing-local-changes.md)
* [Claude Code](/sonarqube-cli/integrations/claude-code.md)
* [State and storage](/sonarqube-cli/administration/state-and-storage.md)
* [GitHub Copilot](/agent-centric-development-cycle/developer-tools/agent-plugins/github-copilot.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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.