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) with their file and line, filterable to new code
- the security hotspots and their review status
- coverage / duplication measures
Instead of opening SonarQube to judge whether a build is fit to ship, an agent can pull the gate status and examine the specific new-code findings. It can then use the exact component + line as the input for a fix.
Used by: Vulnerability Remediation, Incident Response, and your own agents.
Works with SonarQube Server (including the free Community Build) and SonarQube Cloud.
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. The change is 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. This is 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. As a result, 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
- 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 the token. Copy the token immediately. SonarQube shows it 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.
- Add the Integration in Autoheal
- Go to Integrations in Autoheal and click SonarQube.
- Enter a name (e.g. "Production SonarQube").
- 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): use this if your SonarQube is on a private network that Autoheal can't reach directly. Select a Private Access connection to route requests over your network.
- SonarQube URL: your instance base URL (no
- Test and Save
Click Test Connection to check 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 |
To list projects, Autoheal uses components/search, which a Browse-level token can call. It does not use 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
- Check that the User Token was copied in full. SonarQube shows it only once at creation, and a partial copy is the most common cause. Also check that the token 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: check that 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
- Check that 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_periodhas 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
- Check that the SonarQube URL includes the scheme (
https://orhttp://) and does not include/api