sonarsource/sonarqube-agent-plugins/sonar-integrate

Integrate SonarQube

Guide the user through installing sonarqube-cli (if needed), updating it to the latest version when already installed, authenticating, and completing agent-specific integration. Assume SonarQube itself is already set up; this skill only wires the assistant.

Instructions

Interaction rule: for every finite decision, always present predefined selector options (single-choice or multi-choice as appropriate) instead of asking for free-form text. If the user gives an invalid answer, re-show the same selector.

Step 1 — Check for sonarqube-cli and update it

Check if sonar is available on the PATH by running which sonar (macOS/Linux) or Get-Command sonar (Windows) yourself.

If found: first determine how it was installed, because the upgrade path differs:

• Managed by a package or version manager (e.g. installed via Homebrew or mise — the binary lives under the manager's prefix rather than ~/.local/share/sonarqube-cli/bin): do not run sonar update, as it conflicts with the manager. Run the manager's upgrade command yourself instead (Homebrew: brew upgrade --cask sonarqube-cli; mise: mise upgrade aqua:SonarSource/sonarqube-cli), then go to Step 2. If the upgrade fails, show the output but still continue to Step 2 as long as sonar remains usable.
• Installed via the shell/PowerShell script, or unsure: run `sonar update` yourself and wait for it to finish.
• If it succeeds: briefly tell the user the CLI is up to date (or was upgraded), then go to Step 2.
• If it fails: show the relevant output, suggest they run sonar update manually (e.g. offline or network issues), then still continue to Step 2 if sonar remains usable — do not block the rest of the flow unless the binary is missing or broken.

If not found: pick an install command from the table below, show it to the user, and ask for explicit confirmation before running it. Do not execute the command until the user confirms.

The shell/PowerShell script is the default and works everywhere. If the user already manages CLIs with Homebrew or mise, prefer that route so future upgrades stay managed by the tool — the Step 1 update above then defers to the manager.

If the user confirms: run the command yourself using a shell command. After it finishes, re-run the PATH check (which sonar or Get-Command sonar) yourself to verify before continuing.

If the user declines: stop the skill and ask the user to install sonarqube-cli manually and then re-invoke the sonar-integrate skill.

Step 2 — Check authentication status

Run sonar auth status yourself using a shell command.

If already authenticated: note the connected server and organisation from the output, then skip directly to Step 4.

If not authenticated: proceed to Step 3.

Step 3 — Authenticate (sonar auth login)

This step requires user interaction — do not run it yourself.

First determine the connection type using a single-choice selector with these options:

1. SonarQube Cloud - EU (default)
2. SonarQube Cloud - US
3. Self-hosted SonarQube Server

Do not ask an open-ended text question for this decision.

Collect:

Build the login command and show it to the user:

Tell the user:

"Run the command below — it will open your browser to log in. The token is stored

securely in your system keychain and never appears in this chat."

Wait for the user to confirm they logged in, then run sonar auth status yourself to verify before continuing.

Step 4 — Agent-specific integration

Container runtime requirement: The SonarQube MCP Server runs inside a container, started via sonar run mcp (which detects Docker, Podman, or Nerdctl). A container runtime must be installed and running for the MCP tools to load — otherwise integration can complete successfully yet no mcp__sonarqube__* tools appear in the session. Verify this yourself: run docker ps (falling back to podman ps / nerdctl ps). If one succeeds, the runtime is up — proceed. If none do, tell the user their container runtime is not running and ask them to start it, then note they must restart the agent session afterward for the tools to load (starting the daemon and restarting the session are the only parts you cannot do for them).

Pick exactly one branch below based on which agent you are. Do not run the other branches.

• Claude Code -> 4.a
• Copilot CLI -> 4.b
• Codex -> 4.c
• Cursor -> 4.d
• Antigravity -> 4.e
• Gemini CLI -> 4.f
• Factory Droid -> 4.g
• Devin -> 4.h

4.a — Claude Code (sonar integrate claude)

Run `sonar integrate claude`, which configures the SonarQube MCP Server, secrets-scanning hooks, and any other supported integration the CLI applies.

It wires MCP (for skills like sonar-quality-gate, sonar-analyze, sonar-coverage, sonar-duplication, sonar-dependency-risks) and secrets-scanning hooks into the user’s Claude Code config, applying to all Claude Code sessions on this machine. When available, SonarQube Vortex analysis hooks are also installed.

Run this command yourself using a shell command:

sonar integrate claude --non-interactive

4.b — Copilot CLI (sonar integrate copilot)

Run `sonar integrate copilot`, which configures the SonarQube MCP Server, secrets-scanning hooks, and any other supported integration the CLI applies.

It wires MCP (for skills like sonar-quality-gate, sonar-analyze, sonar-coverage, sonar-duplication, sonar-dependency-risks) and secrets-scanning hooks into the user’s Copilot CLI config, applying to all Copilot CLI sessions on this machine.

Run this command yourself using a shell command:

sonar integrate copilot --non-interactive

4.c — Codex (sonar integrate codex)

Run `sonar integrate codex`, which configures the SonarQube MCP Server, secrets-scanning hooks, and—when your SonarQube Cloud org has Vortex analysis—a PostToolUse hook on `apply_patch` that surfaces findings inline after edits, applying to all Codex sessions on this machine.

Run this command yourself using a shell command:

sonar integrate codex --non-interactive

4.d — Cursor (sonar integrate cursor)

Run `sonar integrate cursor`, which configures secrets-scanning hooks (beforeSubmitPrompt, beforeReadFile, and preToolUse), MCP, Context Augmentation (when entitled), and Vortex analysis instructions (when entitled), applying to all Cursor sessions on this machine. Note: Cursor's cloud/background agents only pick up hooks installed in the project itself, not machine-wide ones, so those agents won't see the installed hooks.

Run this command yourself using a shell command:

sonar integrate cursor --non-interactive

After integrate completes, tell the user to enable the MCP server manually in Cursor: open Settings → MCP, find the sonarqube entry, and toggle it on. Also tell the user to ensure a container runtime (Docker, Podman, or Nerdctl) is running. A Cursor session restart may be needed for the tools to appear.

4.e — Antigravity (sonar integrate antigravity)

Run `sonar integrate antigravity`, which configures secrets-scanning hooks, prompt-secrets and Vortex analysis instructions, Context Augmentation (when entitled), and MCP in the Antigravity harness, applying to all Antigravity sessions on this machine.

Run this command yourself using a shell command:

sonar integrate antigravity --non-interactive

Tell the user to ensure a container runtime (Docker, Podman, or Nerdctl) is running, and to restart the Antigravity session if MCP tools do not appear after integrate completes.

4.f — Gemini CLI (legacy)

Gemini CLI starts the SonarQube MCP Server via sonar run mcp, which handles container runtime detection (Docker, Podman, Nerdctl) and authentication automatically. Authentication was handled in Steps 2–3.

Confirm that integration is ready — the MCP server will start automatically when Gemini CLI reads `gemini-extension.json`.

Recommend migrating to Antigravity (4.e): run `agy plugin import gemini`, then `sonar integrate antigravity`. Gemini CLI did not support SonarQube hooks or Vortex analysis wiring.

4.g — Factory Droid

Factory Droid starts the SonarQube MCP Server from the plugin's `mcp.json` via sonar run mcp, which handles container runtime detection (Docker, Podman, Nerdctl) and authentication automatically. Authentication was handled in Steps 2–3.

No sonar integrate command applies to Factory Droid. Factory Droid does not support SonarQube hooks or Vortex analysis wiring.

4.h — Devin (sonar integrate devin)

Run `sonar integrate devin`, which configures the SonarQube MCP Server, secrets-scanning hooks, and—when available—Vortex analysis hooks, applying to all Devin sessions on this machine.

Run this command yourself using a shell command:

sonar integrate devin --non-interactive

Tell the user to ensure a container runtime (Docker, Podman, or Nerdctl) is running, and to restart the Devin session so the new hooks and MCP configuration are loaded.

Summary message

After all steps complete, print a summary:

✅ SonarQube integration is ready.
 
  sonarqube-cli:     up to date
  Authentication:    token stored in system keychain
  MCP Server:        configured (ensure a container runtime (Docker, Podman, or Nerdctl) is running, then restart the agent session if tools do not appear)
 
You can verify at any time with:  sonar auth status
To refresh CLI + wiring later:    invoke the sonar-integrate skill again

If path 4.a (Claude Code) was taken, add this line to the summary:

  Secrets scanning:  hooks registered via sonar integrate claude

If path 4.b (Copilot CLI) was taken, add this line to the summary:

  Secrets scanning:  hooks registered via sonar integrate copilot

If path 4.c (Codex) was taken, add this line to the summary: