Triage Sonarqube

SonarCloud triage skill

This skill drives the SonarCloud Web API (https://docs.sonarsource.com/sonarcloud/api/) to enumerate findings and apply triage decisions: False Positive / Won't Fix / Confirmed for issues; Reviewed with one of Safe / Acknowledged / Fixed for hotspots. Family-mode lets you mark every open finding for a rule in one go.

The skill operates on the project configured in .env (see Setup). Scripts auto-detect the repo root and write all artifacts under <repo-root>/.local/.

MANDATORY — keep this skill alive

If you (the agent) discover a new pattern, gotcha, working flow, correction, or any piece of knowledge while running this skill — update this SKILL.md AND commit it BEFORE proceeding. Knowledge that isn't committed is lost.

Examples of things to capture:

• New rule with a known FP pattern (and the exact comment to use)
• A bulk-FP family that's safe to apply project-wide
• A SonarCloud API quirk (rate limits, undocumented response shapes)
• A new path/issue exclusion that's safer than per-finding marking

Setup

.env entries

# SonarCloud
SONAR_TOKEN='<paste your token from https://sonarcloud.io/account/security>'
SONAR_HOST_URL=https://sonarcloud.io
SONAR_PROJECT=<project_key, e.g. netdata_netdata>
SONAR_ORG=<organization_key, e.g. netdata>

The token is used as HTTP Basic auth username with empty password: -u "$SONAR_TOKEN:" (note the trailing colon).

No browser tab is required — token-based auth is stable across sessions.

Triage decision matrix

Issues (Bug, Vulnerability, Code Smell)

Security Hotspots

Hotspots have a separate state machine. They go from TO_REVIEW to REVIEWED with one of three resolutions:

ASCII-only comments — non-negotiable

api.sonarcloud.io sits behind Cloudflare, which rejects bodies containing non-ASCII bytes (em-dashes, smart quotes) with a 403 challenge. The scripts fail before the network round-trip if non-ASCII is detected.

• Use -- instead of em-dash (U+2014).
• Use straight quotes " ' instead of smart quotes.

Workflow

Step 1 — see what's open

bash .agents/skills/triage-sonarqube/scripts/sonar-search.sh summary

Prints per-rule counts of open issues + open hotspots. Use this to spot high-volume rules that are candidates for family-mode bulk marking, and project-wide quality-profile or exclusion changes.

Step 2 — search for specific rule's findings

Issues:

bash .agents/skills/triage-sonarqube/scripts/sonar-search.sh issues --rule cpp:S5827

Hotspots:

bash .agents/skills/triage-sonarqube/scripts/sonar-search.sh hotspots --status=TO_REVIEW \
  | jq '.hotspots[] | select(.ruleKey=="c:S5443")'

Step 3 — triage

Single finding

bash .agents/skills/triage-sonarqube/scripts/sonar-mark.sh fp     <ISSUE_KEY> "<COMMENT>"
bash .agents/skills/triage-sonarqube/scripts/sonar-mark.sh wontfix <ISSUE_KEY> "<COMMENT>"
bash .agents/skills/triage-sonarqube/scripts/sonar-mark.sh confirm <ISSUE_KEY> "<COMMENT>"

bash .agents/skills/triage-sonarqube/scripts/sonar-mark.sh safe  <HOTSPOT_KEY> "<COMMENT>"
bash .agents/skills/triage-sonarqube/scripts/sonar-mark.sh ack   <HOTSPOT_KEY> "<COMMENT>"
bash .agents/skills/triage-sonarqube/scripts/sonar-mark.sh fixed <HOTSPOT_KEY> "<COMMENT>"

Family mode (every open finding for a rule)

bash .agents/skills/triage-sonarqube/scripts/sonar-mark.sh family-fp   <RULE_ID> "<COMMENT>"
bash .agents/skills/triage-sonarqube/scripts/sonar-mark.sh family-safe <RULE_ID> "<COMMENT>"

Family mode prints all matched keys and prompts before acting unless SONAR_MARK_YES=1 is set.

Step 4 — dry runs

SONAR_DRY_RUN=1 bash .agents/skills/triage-sonarqube/scripts/sonar-mark.sh fp KEY "Comment"

In dry-run mode, write API calls (mark issues, change hotspot status, add comments) are printed but not executed. Read API calls (issue search, hotspot search used to enumerate findings in family mode) still run -- otherwise family mode could not show what it would have acted on.

What this skill does NOT do

• Disable rules: use api/qualityprofiles/deactivate_rule directly, or do it in the SonarCloud UI under Quality Profiles.
• Configure issue exclusions: use Project Settings -> Analysis Scope -> Issue Exclusions in the UI.
• Rule-tuning audit: when you want a per-rule KEEP/DISABLE/NARROW decision log, document that separately (it's project-wide policy, not per-finding triage).

Project-wide quality profile / exclusion configuration

Effective profile lookup:

GET /api/qualityprofiles/search?project=$SONAR_PROJECT&organization=$SONAR_ORG

To make project-wide changes (deactivate a rule or override severity):

1. Copy the inherited profile (api/qualityprofiles/copy)
2. Make your edits there
3. Assign the project to the new profile (api/qualityprofiles/add_project)

This is a one-shot operation per language. SonarCloud language keys are: c, cpp, go, javascript, py, shell, plsql, docker, css, ipynb, php (and others depending on the project). Note the rule-id namespaces in api/issues/search results may differ from the language keys -- e.g. shell rules use the shelldre: prefix, Go rules can use either go: or godre: depending on which analyzer fired -- so the language argument to qualityprofile APIs is the SHORT key (shell, go), not the rule-namespace prefix.

Keep a record of profile decisions in a project-local doc under .local/audits/sonarqube/.

Failure modes — quick diagnosis

Recurring tips

• api/issues/search is paged at ps=500 max. The sq_paginate helper in _lib.sh walks every page until paging.total; use it from any new script instead of re-implementing the loop.
• PR new-code measures returned by api/measures/component_tree are stored under measures[].periods[0].value, not measures[].value. This matters for quality-gate metrics such as new_duplicated_lines, new_duplicated_lines_density, and new_lines.
• Hotspot ruleKey filtering is client-side (search only filters by status/project), so the family-mode helper does it in Python.
• An issue may be transitioned only between certain states; if you get "Cannot do transition from STATUS X to Y", it's already past that state.
• SONAR_DRY_RUN=1 is the right knob when iterating on comments before committing to a bulk operation.