SonarCloud Skill

An open-agent skill for inspecting and managing SonarCloud and SonarQube findings.

This repository provides:

• a reusable sonar-manage-findings skill (SKILL.md)
• a Python CLI helper to query and triage project findings
• GitHub automation for security/scanning hygiene

What this skill can do

With a Sonar token in an environment variable, you can:

• summarize project quality state (issues, hotspots, quality gate, selected metrics)
• list and inspect issues/hotspots
• comment, assign, retag, and transition issues (resolve, wontfix, falsepositive, etc.)
• review hotspots (SAFE, FIXED, etc.)
• inspect measures, measure history, analyses, and Compute Engine tasks
• inspect or mutate project settings, quality gate/profile association, and project tags
• fall back to direct API calls for unsupported endpoints

The helper is repository-agnostic: pass --repo to any local checkout, or pass explicit --project-key / --base-url.

Repository layout

SKILL.md
agents/
  openai.yaml
assets/
  sonar-manage-findings-small.svg
  sonar-manage-findings.png
scripts/
  manage_sonar_findings.py
  sonar_manage_api.py
  sonar_manage_common.py
  sonar_manage_diagnostics.py
  sonar_manage_issues.py
  sonar_manage_project.py
  sonar_manage_render.py
README.md
CONTRIBUTING.md
SECURITY.md
CHANGELOG.md

Agent compatibility

This is a root SKILL.md package. npx skills can install it directly from GitHub, and npx skills experimental_sync can discover it from node_modules because the npm package ships SKILL.md at the package root.

Use --agent universal for agents that consume the shared .agents/skills layout. Use --agent "*" only when you intentionally want to install to every supported agent directory.

npx skills add Nick2bad4u/SonarCloud-Skill -g --agent universal -y
npx skills add Nick2bad4u/SonarCloud-Skill -g --agent "*" -y
npm install --save-dev sonar-manage-findings-skill
npx skills experimental_sync --agent universal -y

OpenAI-specific display metadata lives in agents/openai.yaml. The portable skill contract is SKILL.md plus the referenced assets/ and scripts/ files.

Publishing

The skill is packaged for GitHub releases and npm as sonar-manage-findings-skill.

Verify the package locally before publishing:

npm run release:verify
npm publish --access public --provenance

GitHub Actions publishes with npm OIDC trusted publishing using npm publish --access public --provenance. Configure the npm package trusted publisher for repository Nick2bad4u/SonarCloud-Skill and workflow .github/workflows/release-skill.yml. The workflow intentionally does not use npm stage commands.

Quick start

1) Prerequisites

• Python 3.10+
• A Sonar token exported to an environment variable (recommended: SONAR_TOKEN)

2) Set your token (do not pass it on CLI)

PowerShell

$env:SONAR_TOKEN = "<your-token>"

Bash

export SONAR_TOKEN="<your-token>"

3) Run the helper

From repository root:

python "scripts/manage_sonar_findings.py" summary --repo "."

Machine-readable output:

python "scripts/manage_sonar_findings.py" summary --repo "." --json

Common commands

# List open/reopened issues
python "scripts/manage_sonar_findings.py" list-issues --repo "." --issue-statuses OPEN,CONFIRMED,REOPENED

# Show issue activity
python "scripts/manage_sonar_findings.py" issue-changelog --repo "." --issue AZ123

# Resolve an issue (dry-run first)
python "scripts/manage_sonar_findings.py" transition-issue --repo "." --issue AZ123 --transition resolve --comment "Fixed in code." --dry-run

# List hotspots awaiting review
python "scripts/manage_sonar_findings.py" list-hotspots --repo "." --hotspot-status TO_REVIEW --include-details

# Check quality gate
python "scripts/manage_sonar_findings.py" quality-gate-status --repo "."

For the full command surface and workflows, see:

• SKILL.md

Security notes

• Never paste tokens into command arguments or commit them to git.
• Prefer environment variables and secret managers.
• Use --dry-run before bulk mutation actions.

More details: SECURITY.md

Contributing

Contributions are welcome. Please read:

• CONTRIBUTING.md
• CHANGELOG.md

Releases and downloads

This repository includes a release workflow that creates a downloadable zip bundle:

• Workflow: .github/workflows/release-skill.yml
• Trigger:
  • push a tag like v0.1.0
  • run manually via workflow_dispatch with:
    • release_type: patch / minor / major
    • version: optional explicit x.y.z (overrides release_type)
    • ref: branch to release from (default main)
• Asset: sonarcloud-skill-<tag>.zip

Examples:

# Manual patch bump from main
gh workflow run "Release Skill Bundle" -f release_type=patch -f ref=main

# Manual explicit release version
gh workflow run "Release Skill Bundle" -f release_type=patch -f version=0.2.0 -f ref=main

License

Released under The Unlicense.