sqa: SonarQube findings for coding agents
sqa wraps the official SonarSource sonar CLI. It lists SonarQube findings
ranked security first, explains each one, and, only after the user
approves, fixes the code or records a triage decision in SonarQube.
Start
Run sqa doctor first. If it fails, stop and relay its fix to the user.
Report the quality gate summary of sqa findings (summary) to the user.
Hard rules
- No MCP. Never use, install, configure or call any SonarQube MCP server,
even if one is available. Use only the
sqacommands below. - Never run
sonar integrateorsonar remediate. - Never call
sonar apidirectly; use thesqacommands below. - Never run
sonar auth login,sqa auth loginorsqa auth logoutyourself. The user handles authentication. - Never set, read, print, echo or store a token, and never touch the
SONARQUBE_CLI_TOKENvariable,credentials.jsonor the keychain. - Always ask before any triage decision (see "Human in the loop").
- Never mark a finding as false positive or accepted to reduce the count or to make a quality gate pass. Every decision needs a real justification.
Triage order (security first)
sqa findings already returns findings in this order. Work top-down:
- Vulnerabilities (software quality SECURITY / type VULNERABILITY)
- Security hotspots to review or acknowledged (fix pending), by vulnerability probability HIGH > MEDIUM > LOW
- Reliability (RELIABILITY / BUG)
- Maintainability (MAINTAINABILITY / CODE_SMELL)
Within a tier: severity (BLOCKER > HIGH > MEDIUM > LOW > INFO; standard severities CRITICAL=HIGH, MAJOR=MEDIUM, MINOR=LOW), new code first, then file and line.
Commands
Read-only, run freely:
| Command | Use |
|---|---|
sqa doctor | Check that sonar is installed, authenticated and that the server is 2025.1+. |
sqa auth status | Show which SonarQube server sonar is connected to (never shows the token). |
sqa findings [--project P] [--branch B | --pr N] [--file F] [--new-code] [--min-severity S] [--security-only] [--limit N] | Ranked overview. Use when the user asks for the list, or to present several at once. The pr column shows an open fix PR for a finding. It ends with a quality gate summary: coverage and "security hotspots reviewed" against the gate. |
sqa next [same filters] [--skip KEY]… [--include-open-pr] | Highest-priority finding without an open fix PR, with the full brief (rule, why, location, code context, fix guidance). The default way to work one by one. skipped lists what it passed over. |
sqa show <key> | Brief for a specific key (one from findings, or that the user names), including any open fix PR. |
sqa coverage [--project P] [--branch B | --pr N] [--top N] [--overall] | Files ranked by uncovered lines on new code (overall when there is no new-code period), with the gate's coverage condition. |
sqa pr-body <key>... | --from-findings [filters] [--reason TEXT] | Markdown "Resolves SonarQube findings" block for a PR body, one line per finding (message linked to SonarQube, rule, location, key). |
sqa coverage --file <file> | That file's uncovered line ranges and partly covered conditions (--file <dir> ranks the files below it). |
findings, next and show look up open fix PRs once per run through gh (or, without it,
remote sonar/* branches via git ls-remote). pr_check says which was used;
if it is unavailable, nothing was skipped and the note says why. Then
check the forge yourself before opening a PR. --no-pr-check turns the lookup
off.
State-changing, only after explicit user approval of that specific finding:
| Command | Use |
|---|---|
sqa mark <issue-key> fp|accept|reopen --comment "<reason>" --approved-by-user | Issue false positive / accepted / reopen. |
sqa hotspot <hotspot-key> safe|fixed|acknowledged --comment "<reason>" --approved-by-user | Review a security hotspot. |
sqa hotspot <hotspot-key> reopen --comment "<reason>" --approved-by-user | Set a reviewed hotspot back to TO_REVIEW. |
sqa hotspot <hotspot-key> comment --comment "<text>" --approved-by-user | Add a comment to a hotspot without changing it. |
sqa hotspot <hotspot-key> assign <login> --comment "<reason>" --approved-by-user | Assign a hotspot to a SonarQube user (only TO_REVIEW or ACKNOWLEDGED). |
Comments and assignments are visible to the team in SonarQube, so they need the same explicit approval as a verdict: show the user the exact comment text or the login first.
If sqa findings cannot determine the project, ask the user for the project
key and pass --project <key>.
Scope: without --branch/--pr, every command reads the project's
main branch in SonarQube, whichever branch you have checked out: sqa never
derives a branch or PR from the local git checkout (plain sonar list issues
would). That is what the fix loop needs, since fixes branch from the default
branch, so you can stay on a fix branch and still see the main-branch queue.
Use --branch/--pr only when the user asks about a specific analysed branch
or pull request.
Add --dry-run to preview a state change. Output defaults to the compact
TOON format when piped; add --format json if you need JSON.
Exit codes: 0 ok, 1 findings at or above --fail-on (for sqa coverage:
coverage below --fail-on <percent> or no coverage data), 2 usage or config error, 3 auth or
server error, 4 approval missing.
Human in the loop
You recommend, the user decides, then you act.
- Run
sqa next(it includes the brief; no separateshowis needed). - Present the finding with your recommended verdict and reasoning, using the template below. Verdicts: fix in code, false positive, accept (won't fix), and for hotspots safe, fixed or acknowledged.
- Stop and ask the user explicitly. Do nothing until they answer for this specific finding.
- Only after a clear yes for that finding:
- fix: edit the code in your normal flow, then follow the fix loop.
- false positive / accept / reopen:
sqa mark <key> <verdict> --approved-by-user --comment "<the user's reasoning>" - hotspot:
sqa hotspot <key> safe|fixed|acknowledged|reopen --approved-by-user --comment "<the user's reasoning>" - hotspot comment / assign:
sqa hotspot <key> comment|assign <login> --approved-by-user --comment "<the text the user approved>"
- Approval covers only the findings the user named. "Go ahead", "fix them all" or similar does not extend to findings you have not presented. Present new ones first. You may present several findings in one message, numbered, and the user may approve them individually or as that list.
- If the user disagrees with your verdict, follow their decision and put their reasoning in the comment.
--approved-by-user is your statement that the user approved this exact
action. Never pass it otherwise.
Presentation template
[<rank>] <category> · <severity> · <rule> (key: <key>)
Where: <file>:<line> (new code: yes/no)
What: <message>
Why it matters: <one or two sentences from the rule description>
Recommendation: <fix | false positive | accept | safe | fixed | acknowledged | reopen>
Reasoning: <why, referring to the actual code>
Proposed change: <short description or diff, if fixing>
Do you approve this? (yes / no / different verdict)
Hotspots with status REVIEWED/ACKNOWLEDGED were already reviewed: the risk
is confirmed and a fix is pending. Recommend the fix (then fixed once the
fix is merged and analysed), or ask whether the user wants to reopen it or
mark it safe. --no-acknowledged hides them.
If the finding is in test code (tests, fixtures, helpers), consider whether it
matters there (hardcoded credentials in fixtures or weak crypto/random in helpers
often do not). You may recommend accept, or that the user exclude those paths
(sonar.tests/sonar.test.inclusions, sonar.exclusions, sonar.issue.ignore.multicriteria).
Still recommend a fix when that code is shipped, shared, or reveals a real bug;
never edit Sonar settings or exclusions without explicit approval.
Fix loop
- Pick the highest-ranked finding the user approved for fixing.
sqa nextalready skips findings with an already-open PR (the key is in the PR body's SonarQube URL, or the head branch issonar/<rule>-<key>). If the brief orfindingsshows aprfor the finding, tell the user (with the PR link), do not open another, and ask how to proceed. Ifpr_checkisunavailableorgit(a remote branch, maybe without a PR), check yourself before branching, e.g.gh pr list --state open --label sonar --search "<key> in:body"orgit ls-remote --heads origin 'sonar/*<key>*'. To pass over a finding the user wants to leave for now, runsqa next --skip <key>(repeatable); never skip findings on your own to avoid them. Otherwise check out the default branch and pull it (git pull --ff-only), then branch from it (e.g.sonar/<rule>-<key>, lowercased and sanitized; keep the key at the end so sqa can find the branch); never stack on a previous fix branch. One finding per branch/PR unless the user explicitly approved grouping those findings. Ask before creating the branch, pushing or opening the PR (a visible write), unless the fix approval already included that. - Use the brief from
sqa next(orsqa show <key>) and the surrounding code; make the smallest correct fix. Do not suppress the rule with comments or annotations unless the user explicitly approved that. Commit only that fix (plus any test change for it). Message and PR title: Conventional Commits<type>(<scope>): <summary>, usuallyfix(security or bugs),refactor/stylefor maintainability smells, ortestif only tests change; include the rule key, e.g.fix(security): use parameterized query in getUser (go:S3649). PR body: short why, what changed, tests run, and the block fromsqa pr-body <key>...listing every finding the PR resolves (see "Findings a PR resolves" below). Apply thesonarlabel; if it is missing, ask before creating it, or tell the user. - Run the project's tests and linters. Show the user the change, then open the PR with the harness's normal git/forge tooling. Never merge it yourself.
- SonarQube only updates after a new analysis (CI or the user's usual scan). After
it runs, verify with
sqa show <key>orsqa findings. Return to the default branch, pull it, runsqa next(it skips the finding you just opened a PR for), and present that finding before touching it.
Findings a PR resolves
- List every finding the PR resolves in its body, one line each, with
sqa pr-body <key> [<key>...]. It prints a "Resolves SonarQube findings" block: message linked to the finding in SonarQube, rule key and name, location and the key. Paste it unchanged; the keys are howsqa nextandsqa findingsrecognise that a finding already has a PR. This includes findings the PR resolves indirectly (an exclusion, a config change, a fix that removes several findings at once). - Grouping needs explicit approval first. One finding per PR is the default. Before putting several findings in one PR, show the user the list and get a yes for that grouped PR.
- Never add an unrelated fix silently. If you notice something else while fixing, present it as a separate finding or change and ask.
Config fixes (exclusions, test inclusions, coverage exclusions)
A change to sonar.exclusions, sonar.tests/sonar.test.inclusions,
sonar.coverage.exclusions, sonar.issue.ignore.multicriteria or similar
removes every finding it covers, not just the one you were looking at:
- Only propose it when it is justified (e.g. test fixtures, generated code), and never change Sonar settings without explicit approval.
- Before changing anything, list every finding the change will remove:
sqa findings --file '<glob>'(globs liketest/**or**/*_test.goare matched by sqa). Show the user that list and ask for approval of this grouped PR. - In the PR body, put the block from
sqa pr-body --from-findings --file '<glob>' --reason "<the exclusion, e.g. excluding test fixtures via sonar.exclusions>"(or the named keys), so the body states that these findings are resolved by the exclusion.
Coverage
sqa findings ends with a coverage line. When coverage on new code fails the
gate, or the user asks about coverage:
- Run
sqa coverageand present the files with the most uncovered lines on new code. For a file the user picks, runsqa coverage --file <file>to see the uncovered line ranges and partly covered conditions (branches). - Coverage is not triage: there is nothing to mark. Writing tests is normal
code work and follows the fix loop: propose which tests you would add, ask
before creating a branch or opening a PR, one PR per change unless the user
approved grouping it (e.g.
test(<scope>): cover <what>), from the up-to-date default branch. - Test real behaviour. Never write tests that only execute lines without asserting anything, and never change coverage settings, exclusions or the gate's threshold without explicit approval.
- The numbers change only after the next analysis that imports a coverage
report (usually CI). If
sqa coveragesays there is no line coverage for a file, the coverage report did not include it; tell the user rather than guessing.