SonarQube Integration

Connect SonarQube to let agents read your code-quality and security posture: whether a project's quality gate passes and exactly which conditions failed, the issues (bugs, vulnerabilities, code smells) — filterable to new code — with their file and line, the security hotspots and their review status, and coverage / duplication measures. Instead of opening SonarQube to judge whether a build is fit to ship, an agent can pull the gate status, drill into the specific new-code findings, and use the exact component + line as the input for a fix.

Used by: Vulnerability Remediation, Incident Response, and custom agents.

Works with SonarQube Server (including the free Community Build) and SonarQube Cloud.

note

Read-only. Autoheal reads your SonarQube projects, quality gates, issues, hotspots, and measures; it never assigns issues, marks hotspots reviewed, edits quality gates, or triggers analyses. Any change to your code to fix a finding happens in your own repositories as a pull request that a human reviews — never written back to SonarQube.

Capabilities

Once connected, agents can:

Capability	Description
Quality gate status	Read a project/branch/PR's gate result (OK / ERROR) and each failing condition (metricKey, comparator, errorThreshold, actualValue) — the "is this fit to release?" answer
List issues	Read bugs, vulnerabilities, and code smells with file, line, rule, severity, type, and status; filter by severity/type/status and to new code only
Issue detail	Read one issue's full detail (rule, flows, comments) by key
Security hotspots	Read security-sensitive code needing review, with securityCategory, vulnerabilityProbability, status (TO_REVIEW / REVIEWED) and resolution
Hotspot detail	Read one hotspot's full detail — the rule's risk description and fix recommendations — the remediation input for a fix
Measures	Read metrics — coverage, duplications, and their new-code counterparts, plus bug/vulnerability/code-smell/hotspot counts and lines of code
List projects	Enumerate the projects your token can see

Agents read SonarQube through its Web API (/api/*) at the URL you provide.

Prerequisites

• A SonarQube Server instance (any recent version, including Community Build) reachable from Autoheal, or a SonarQube Cloud organization
• A user token with Browse permission on the projects you want Autoheal to read (no administration rights are needed)

Authentication

Autoheal authenticates with a single user token — the same token you would use for any SonarQube API call. Autoheal sends it in the way that every SonarQube edition accepts (HTTP Basic with the token as the username), so it works across SonarQube Server versions, Community Build, and SonarQube Cloud without any per-version configuration.

Field	What you provide
SonarQube URL	Your instance base URL, e.g. https://sonarqube.internal (Server / Community Build) or https://sonarcloud.io (Cloud). Do not include /api.
User Token	A token generated under My Account → Security → Generate Tokens. A read-only token with Browse permission is sufficient.
Organization Key	SonarQube Cloud only — your organization key. Leave blank for SonarQube Server.

Setup

1

Generate a token in SonarQube

In SonarQube, click your avatar → My Account → Security → Generate Tokens. Give it a name (e.g. "Autoheal"), choose the User Token type, and generate it. Copy the token immediately — it is shown only once.

A user with Browse permission on the target projects is enough; Autoheal never writes to SonarQube, so no administration or edit rights are required.

SonarQube Cloud: note your organization key (shown in your organization's URL and settings) — you'll need it below.

2

Add the Integration in Autoheal

1. Go to Integrations in Autoheal and click SonarQube.
2. Enter a name (e.g. "Production SonarQube").

3

Configure Credentials

• SonarQube URL: your instance base URL (no /api).
• User Token: paste the token.
• Organization Key: for SonarQube Cloud only; leave blank for Server.
• Private Access connection (optional): if your SonarQube is on a private network Autoheal can't reach directly, select a Private Access connection to route requests over your network.

4

Test and Save

Click Test Connection to verify the URL and token, then Save.

Required Permissions

Autoheal only reads. A token from a user with Browse permission on the projects is sufficient:

SonarQube resource	Access	Why it's needed
Projects (Browse)	read	Enumerate projects and read their issues, gate, hotspots, and measures
Quality gates	read	Project/branch/PR pass-fail and failing conditions
Issues	read	Bugs, vulnerabilities, code smells (the findings)
Security hotspots	read	Security-sensitive code and its review status
Measures	read	Coverage, duplications, and new-code metrics

Listing projects uses components/search (which a Browse-level token can call) rather than projects/search (which requires administration) — so a least-privilege read token is all you need.

Example Queries

Once connected, you can ask an agent questions like:

Is the "payments-service" project on main fit to release? If not, which quality gate conditions failed?

List the new-code vulnerabilities and bugs in payments-service, with file and line.

Show the security hotspots in payments-service that are still TO_REVIEW.

What's the coverage and duplication on new code for payments-service?

Troubleshooting

401 Unauthorized / token invalid

• Confirm the User Token was copied in full (it is shown only once at creation — a partial copy is the most common cause) and has not expired or been revoked
• Regenerate the token if unsure and update the integration

403 Forbidden / empty project list

• The token's user lacks Browse permission on the project — grant Browse on the projects Autoheal should see
• SonarQube Cloud: confirm the Organization Key is set and correct; without it, Cloud calls return no results

Empty results for a project

• Project keys are case-sensitive — copy the exact key from the project list
• Confirm the token's user can see that project (private projects require explicit Browse permission)

New-code filter returns nothing

• "New code" filtering requires a New Code period to be defined for the project in SonarQube (Project Settings → New Code). Without one, in_new_code_period has nothing to compare against

Self-hosted SonarQube can't be reached

• For a SonarQube on a private network, add a Private Access connection to the integration so Autoheal routes requests over your network
• Confirm the SonarQube URL includes the scheme (https:// or http://) and does not include /api