sonarsource/sonarqube-agent-plugins/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

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

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:

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:

{
  "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:

{
  "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:

{
  "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.

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

1. 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).
2. 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):