sonar-quality-gate

# SonarQube — Quality gate Report **only** the quality gate evaluation for a SonarQube project: overall status, every **condition** returned by the API, and worst-offender breakdowns for failing conditions. Do not pull a broad measures dashboard here — for numeric metrics beyond the gate (coverage %, issue counts, ratings as measures, and so on), use **`mcp__sonarqube__get_component_measures`** afterward with the `metricKeys` you care about. ## Usage ``` sonar-quality-gate # quality gate for the current project sonar-quality-gate my-project # quality gate for a specific project key sonar-quality-gate my-project --branch release/2.0 sonar-quality-gate my-project --pr 42 ``` ## Prerequisites This skill uses the `sonarqube-cli` command **`sonar quality-gate status`** (alias `sonar qg status`) as the primary path — don't invent other ones (e.g. `sonar mcp call` does not exist). Prefer it over the MCP tool: the CLI returns worst-offender breakdowns per failing condition in the same call — see Step 5 — while the MCP tool needs separate follow-up calls (measures, issues) for that detail. **Before proceeding**, verify `sonar` is available on your PATH and authenticated. If it is **not installed or not authenticated**, the MCP fallback cannot help either — the SonarQube MCP Server is itself started via `sonar run mcp` and shares the CLI's stored credentials (true whenever it was set up through the sonar-integrate skill; doesn't apply if the `sonarqube` MCP server was configured independently, e.g. via a standalone Docker container with its own token) — so skip straight to the message below and recommend the sonar-integrate skill. Only when `sonar` works but `quality-gate status` itself is unavailable (unknown subcommand on an older CLI, or the command errors for another reason) fall back to the MCP tool `mcp__sonarqube__get_project_quality_gate_status` in Step 3. **If the MCP fallback also fails (for example the tool is unavailable, or no project key can be resolved), narrow down the cause** — check whether the `sonarqube` MCP server is enabled in this agent's configuration. - **Not enabled / not registered** → recommend running the sonar-integrate skill. - **Enabled but its tools are still unavailable** → configuration is correct but the server failed to start. The most common cause is that the container runtime is not running — the MCP server launches inside Docker/Podman/Nerdctl via `sonar run mcp`, so a correctly configured server still produces no tools if the daemon is stopped. Run `docker ps` yourself (falling back to `podman ps` / `nerdctl ps`) to confirm which cause applies: if it errors, the runtime is down; after the user starts it, confirm the same command succeeds before asking them to restart the agent session. Either way, show the user: > Unable to run `sonar quality-gate status`, reach the SonarQube MCP Server, or resolve a project key. > > **Possible causes:** > - `sonarqube-cli` not installed or not authenticated — invoke the sonar-integrate skill > - MCP server not registered — invoke the sonar-integrate skill to configure the SonarQube MCP Server, then restart the agent session > - Container runtime not running — the SonarQube MCP Server runs inside a container (Docker, Podman, or Nerdctl); start your container runtime, then restart the agent session > - Credentials not configured — invoke the sonar-integrate skill > - Project key is wrong or no default project in MCP config — pass an explicit key, or verify `sonar-project.properties` / re-run the sonar-integrate skill for this project Then ask the user (yes/no) whether to run the sonar-integrate skill now. Briefly explain what it does: it checks the SonarQube setup on their machine — installing or updating `sonarqube-cli` and verifying authentication — and re-configures the integration for this agent, including the SonarQube MCP server and secrets-scanning hooks. If they confirm, invoke the sonar-integrate skill yourself and follow it end-to-end in this session, then ask the user to ensure a container runtime (Docker, Podman, or Nerdctl) is running and to restart the agent session so the new MCP tools become available; if they decline, stop. ## Instructions ### Step 1: Resolve the project key (only when needed) `sonar quality-gate status` does **not require** `-p` — unlike `sonar list issues` (where it's mandatory), it resolves the project from `sonar.projectKey` in `sonar-project.properties` when `-p` is absent. Resolve a key only when you must pass it (the user targets another project, or you fall back to the MCP tool in Step 3 and its schema requires it): - If the user provided a project key, use it. - Otherwise look for `sonar.projectKey` in `sonar-project.properties` at the repo root. - If still not found, **omit `-p`** on the CLI and let it auto-resolve. For the MCP fallback, **omit `projectKey`** and rely on the integration default instead. ### Step 2: Parse optional filters from the user-provided arguments | Flag | CLI option | MCP parameter (fallback) | | ----------------- | ---------------- | ------------------------- | | `--branch <name>` | `--branch` | `branchKey` | | `--pr <id>` | `--pull-request` | `pullRequestKey` | `--branch` and `--pr` are mutually exclusive — if the user passes both, stop and ask which one they mean. Omit flags/keys not provided. If the MCP tool uses different parameter names, follow the schema exposed by your SonarQube MCP server. ### Step 3: Run `sonar quality-gate status` Before running the command, validate the values you are about to interpolate — project key against `^[a-zA-Z0-9_\-\.:]+$`, `--branch` against `^[a-zA-Z0-9_\-\./]+$`, `--pull-request` digits only (same rules as the sonar-list-issues skill). If any value fails, stop and tell the user what was rejected instead of running the command. ```bash sonar quality-gate status [-p <project-key>] [--branch <name> | --pull-request <id>] --format json ``` Always use `--format json` and parse it — don't relay the CLI's default `table` output straight to the user; route the parsed result through Step 4's formatting. The command returns a top-level **`status`** (`OK`, `ERROR`, or other values your server uses) and a **`conditions`** array. Each condition typically includes: | Field | Meaning | | ---------------- | ----------------------------------------------------------------------- | | `metricKey` | SonarQube metric identifier for the gate condition | | `status` | Per-condition result (`OK`, `ERROR`, …) | | `errorThreshold` | Required bound when the gate defines one (may be absent for some types) | | `actualValue` | Value SonarQube compared against the threshold | On a CLI new enough to support it, the same call also returns a **`breakdown`** on each failing condition — see Step 5, don't fetch it separately; if `breakdown` is absent, treat that as "not available", not an error. **Example (all conditions OK)** — response shape: ```json { "status": "OK", "conditions": [ { "metricKey": "reliability_rating", "status": "OK", "errorThreshold": "2", "actualValue": "1" }, { "metricKey": "security_rating", "status": "OK", "errorThreshold": "1", "actualValue": "1" }, { "metricKey": "new_duplicated_lines_density", "status": "OK", "errorThreshold": "3", "actualValue": "0.0" } ] } ``` **Example (failing gate)** — note missing `errorThreshold` on some conditions is normal: ```json { "status": "ERROR", "conditions": [ { "metricKey": "new_coverage", "status": "ERROR", "errorThreshold": "85", "actualValue": "82.50562381034781" }, { "metricKey": "new_blocker_violations", "status": "ERROR", "errorThreshold": "0", "actualValue": "14" }, { "metricKey": "new_sqale_debt_ratio", "status": "OK", "errorThreshold": "5", "actualValue": "0.6562109862671661" }, { "metricKey": "reopened_issues", "status": "OK", "actualValue": "0" }, { "metricKey": "open_issues", "status": "ERROR", "actualValue": "17" } ] } ``` **If `sonar quality-gate status` itself is unavailable (unknown subcommand on an older CLI, or the command fails for a reason other than a missing/unauthenticated CLI), fall back to `mcp__sonarqube__get_project_quality_gate_status`.** If `sonar` is not installed or not authenticated, don't try the MCP tool — the MCP server runs via `sonar run mcp` and shares the CLI's credentials, so it will be unavailable too — unless the `sonarqube` MCP server was configured independently (e.g. via a standalone Docker container with its own token), in which case the MCP tool may still work, so try it; show the message in Prerequisites and recommend sonar-integrate instead. Include **`projectKey` only if** you resolved one in Step 1 **and** the tool requires it; otherwise omit it and rely on the integration default. Example payload: ```json { "projectKey": "<only-if-required>", "branchKey": "<name, if --branch was given>", "pullRequestKey": "<id, if --pr was given instead>" } ``` Include `branchKey` only when `--branch` was given, and `pullRequestKey` only when `--pr` was given — never both (see Step 2). Omit `projectKey` from the payload when the integration default applies. Omit unused keys. The tool returns the same `status`/`conditions` shape as above, but with **no `breakdown`** — see Step 5. ### Step 4: Format the results Present a concise report: 1. **Headline** — Map top-level `status` to plain language (e.g. `OK` → passed, `ERROR` → failed). Include project key and branch/PR context if known. 2. **Conditions table** — One row per element of `conditions`, columns at minimum: - **Metric** — `metricKey` (humanize lightly if you know the name; otherwise keep the key). - **Condition status** — `status`. - **Threshold** — `errorThreshold` when present; use `—` when absent. - **Actual** — `actualValue` when present; use `—` when absent. Sort so failing conditions (`ERROR` or non-OK, per server rules) appear **before** passing ones. 3. **Ratings** — For keys like `reliability_rating` / `security_rating`, SonarQube often encodes ratings as numeric grades in the API (for example 1 = A, 5 = E). Mention that interpretation when it helps the user. 4. **No extra measures** — Do not call `get_component_measures` inside this skill unless the user explicitly asks for deeper metrics in the same turn. When they need more detail, tell them the next step (see Step 6). 5. **Breakdown (CLI path only)** — When a condition carries a `breakdown` (Step 3's primary CLI path, new enough CLI version), render it as a short indented list under that condition's row using the fields relevant to its category (see Step 5 for the shape per category). Skip this entirely when `breakdown` is absent or you're on the MCP fallback. If the quality gate payload is missing or analysis has not run, say so clearly instead of inventing values. ### Step 5: Treat failing conditions by category A failing gate is rarely one flat list — treat each failing condition according to the kind of metric it is. On the **primary CLI path**, this is close to free: `sonar quality-gate status` already groups every failing condition's worst offenders into a `breakdown` (or, on an older CLI without this enrichment yet, no `breakdown` field at all — treat that the same as "not available", not an error). On the **MCP fallback**, the tool gives you `conditions` only, with no breakdown — use the metric key to categorize below, then hand off to the matching skill for detail. Example `breakdown` on a failing coverage condition (CLI path): ```json { "metricKey": "new_coverage", "status": "ERROR", "errorThreshold": "85", "actualValue": "82.5", "breakdown": [ { "file": "src/auth/login.py", "coverage": "42.0" }, { "file": "src/utils/helpers.py", "coverage": "58.3" } ] } ``` Group by metric key: - **Coverage** (`coverage`, `new_coverage`, `branch_coverage`, `line_coverage`, …) — the breakdown lists the worst files by coverage %. Tell the user which files most need tests. For line-level detail on a specific file, hand off to **sonar-coverage**. - **Duplications** (`duplicated_lines_density`, `new_duplicated_lines_density`, `duplicated_blocks`, …) — the breakdown lists the worst files, each with its duplicate block count and the peer files it duplicates. Suggest extracting a shared helper. For the full duplication blocks, hand off to **sonar-duplication**. - **Issues & Security** (`violations`, `bugs`, `code_smells`, `reliability_rating`, `sqale_rating`/`new_maintainability_rating`, and — on a CLI new enough to support it — `vulnerabilities`/`security_rating`) — the breakdown is already the actual failing issues (file, line, key, rule, message), usually enough to act on directly. For broader filtering (severities, statuses, other files), hand off to **sonar-list-issues**. - **Dependency risks** (metric keys starting with `sca_`, e.g. `sca_count_*`, `sca_rating_*`, `sca_severity_*`) — the breakdown is a flat package/version/severity/type list with **no file location**: SCA risks are project-level, not tied to a specific file or line. It reflects unresolved risks already known to the server. For a fresh re-scan of manifests or CVE-level detail, hand off to **sonar-dependency-risks**. If you're on the **primary CLI path** and need to focus on just one category (for example the user asks specifically "why did coverage fail?"), re-run `sonar quality-gate status` with `--category <coverage|duplications|issues|dependency-risks>` (values match the metric groups above; support depends on your CLI version); `--top <n>` controls how many entries each breakdown includes. Leaving `--category` off, as in Step 3, already returns breakdowns for every category at once — only narrow it down on request. On the **MCP fallback** there is no CLI call to re-run: hand off to the matching skill above instead. ### Step 6: Deeper metrics (`get_component_measures`) To investigate **beyond** the gate (e.g. overall coverage, line coverage, bug counts, detailed ratings), call **`mcp__sonarqube__get_component_measures`** with the same branch/PR context if applicable, and pass `metricKeys` for the measures you need. Add **`projectKey` only when** the tool requires it and you have a resolved key; otherwise rely on the integration default (you can start from the `metricKey` values that failed or from the [SonarQube metric keys](https://docs.sonarsource.com/) documentation). **If the tool is unavailable, fall back to `sonar api`** (this one *does* require a resolved project key — unlike `sonar quality-gate status` in Step 3, which auto-resolves from `sonar-project.properties` — if none was resolved in Step 1, ask the user or invoke sonar-list-projects, then stop): ```bash sonar api get "/api/measures/component?component=<project-key>&metricKeys=<comma-separated-keys>[&branch=<name>][&pullRequest=<id>]" ``` If this also fails, show the standard message above — don't guess further commands. ### Step 7: Related skills Only needed for detail beyond what Step 5's breakdown already gave you: - **sonar-list-issues** — filter issues/security findings by severity, status, or beyond the top entries already shown. - **sonar-coverage** — line-by-line coverage detail for a specific file. - **sonar-duplication** — full duplication blocks for a specific file. - **sonar-dependency-risks** — a fresh dependency-risk scan or deeper CVE detail.