Administer Remediation Agent
Information on how to administer the SonarQube Remediation Agent.
Overview
The SonarQube Remediation Agent helps you fix issues found by SonarQube Cloud in pull requests and in your backlog. It generates fix suggestions for eligible issues and verifies the proposed changes before offering them to you.
This page explains how to enable the agent, manage repository access, and control how it operates in GitHub, Azure DevOps, and SonarQube Cloud.
The Remediation Agent is part of Sonar Agent Essentials, a product that requires a separate subscription to your SonarQube Cloud Team (annual) or Enterprise plan.
Requirements and limitations
The SonarQube Remediation Agent, when enabled, can make fix suggestions in new PRs on private projects bound to GitHub or Azure DevOps.
Analysis must be enabled on your repository, either automatic analysis or CI-based analysis.
Your GitHub or Azure DevOps organization and repository must be bound to your SonarQube Cloud organization and project.
Pull request remediation, available for GitHub-bound projects only, fixes new issues in a pull request when the quality gate fails. Azure DevOps-bound projects can use automated and manual backlog remediation.
The agent can suggest code fixes in the main branch of your backlog and on your pull request for maintainability, reliability, and a select set of security issues found in C#, Java, JavaScript/TypeScript, and Python code. The agent can also suggest fixes for secrets detected in your code.
The agent can also fix dependency vulnerabilities found by Software Composition Analysis (SCA). See Reviewing and fixing dependency risks for details.
To keep the agent's output manageable, the number of issues it handles at once is limited:
Automated backlog remediation: each scheduled run opens one pull request for up to 5 issues in every selected repository.
Manual backlog remediation: you can't select more than 20 issues to assign at one time.
Pull request remediation: if a pull request introduces more than 20 new issues, the agent isn't offered.
Warning: The SonarQube Remediation Agent will only work with issues found in one of the supported language types.
Once enabled in SonarQube Cloud, any of your GitHub repositories can add the SonarQube Remediation Agent as a GitHub App, regardless of the language type.
SonarQube Cloud may find issues in a repository with an unsupported language (for example, C++), but the agent won't be triggered in a pull request because C++ isn't a supported language.
Sharing your code with Sonar
If you use the SonarQube Remediation Agent, the affected code is processed by Sonar to generate and verify a fix suggestion. Sonar's remediation service sends the affected code snippet to your provider's LLM to generate the suggestion, then verifies the generated code.
Because you bring your own provider key, the request is made under your own provider account, so your provider's usage agreement governs how your data is handled.
For Sonar terms and conditions, see Early Access terms in our Legal documentation.
Enable your agent
Before you connect the agent, bind your project to its GitHub or Azure DevOps repository and enable analysis, using either automatic analysis or CI-based analysis. Then navigate to Your SonarQube Cloud organization > Administration > AI capabilities > Remediation Agent.
How you connect the agent depends on your DevOps platform.
GitHub: install the SonarQube Agent app
A GitHub administrator needs to install the SonarQube Agent GitHub app. Under Install app, select GitHub. The administrator will be prompted to install the app on the GitHub organization already linked to your SonarQube Cloud organization. If installed, the agent will be granted:
Read and write access to code and pull requests
Read-only access to Actions
Read-only access to issues and metadata
Choose either All repositories or Only select repositories to control which repositories the agent can access. Once you've made your selection, select Install & Authorize to finish the setup. The installation may take a few seconds to complete.
Azure DevOps: reuse your platform connection
Azure DevOps doesn't use a separate app. The agent reuses the personal access token (PAT) captured when your Azure DevOps organization was imported into SonarQube Cloud, so there's no app to install and no install-time repository picker. If your organization isn't imported yet, see Importing an Azure DevOps organization and Azure DevOps project binding.
Select flows and projects
After you connect the agent, Pull request fixes (GitHub only) and Backlog fixes are selected automatically under Enable agent. You'll be able to commit the agent's suggestions directly from your PRs, and the Assign to Agent button will be available on the Issues page for selected projects. Choose whether the agent runs on All projects or Only selected projects.
To have the agent fix backlog issues on a schedule, an organization admin selects Automated backlog remediation at the bottom of the Enable agent list. Set the frequency (daily or weekly), the time, and the timezone for the scheduled runs. To cap how many open pull requests the agent keeps active, set a limit under Pause when open PRs reach, or select Don't pause. These organization-level settings apply to all projects where the agent is enabled, and project admins have the same controls to override or disable the schedule for individual projects.
Configure your LLM provider key
The SonarQube Remediation Agent runs on a large language model (LLM) from an external provider. You bring your own provider API key: add an OpenAI or Anthropic API key to your organization, and the agent uses it to generate fix suggestions.
Because you provide the key, agent usage is billed to your provider account. You need an OpenAI or Anthropic account to use the agent.
Add a provider key
Adding keys is an organization-level task. Navigate to Your SonarQube Cloud organization > Administration > AI capabilities > Configuration, then:
Select Add key.
Choose a provider: OpenAI or Anthropic.
Enter the API key from your provider account.
Enter a name to identify the key in SonarQube Cloud.
Select Save.
When you save, SonarQube Cloud verifies the key with the provider. If the key is valid, it's accepted; if it can't be verified, SonarQube Cloud reports the error and the key isn't saved.
You can add up to three keys per organization. Once you reach that limit, the Add key option is disabled until you delete a key.
Note: You choose the provider, not the model. SonarQube Cloud uses Claude Opus 4.6 for Anthropic and GPT-5.5 for OpenAI.
How your key is handled
Encrypted at rest: keys are encrypted with AWS Key Management Service (KMS) before they're stored.
Never logged: the key value isn't written to logs.
Masked when displayed: after you save a key, SonarQube Cloud only ever shows a masked hint, a few characters from the start and end of the key. The full key is never shown again and is never sent back to the browser, so keep your own copy if you need it elsewhere.
Select the key for the agent
After you add a key, choose which one the agent uses. Navigate to Your organization > Administration > AI capabilities > Remediation Agent, and select your key in the agent setup steps. The agent can't be enabled until a key is selected, so the later setup steps stay disabled until you complete this step.
Manage and delete keys
To review or remove keys, go to Your SonarQube Cloud organization > Administration > AI capabilities > Configuration. Each saved key shows its name, provider, and masked hint.
To delete a key, select it and confirm. If you delete the key currently selected for the agent, the agent is disabled until you select another key.
Manage agent access
GitHub
The SonarQube Remediation Agent only has access to the bound repositories defined in GitHub. To change repository access, a GitHub administrator who is also a SonarQube Cloud Administrator can navigate in SonarQube Cloud to Your organization > Administration > AI capabilities > Remediation Agent. Under Install app, select Manage Permissions which takes you to your GitHub Apps page.
Alternatively, a GitHub administrator can navigate in GitHub to Your GitHub organization > Settings > Third-party Access > GitHub Apps. Under Installed GitHub Apps > SonarQube Agent, select Configure.
In GitHub, under SonarQube Agent > Repository access, add or remove your repositories from the list. When finished, select Save to confirm your selection.
Azure DevOps
The agent's access comes from your Azure DevOps organization binding rather than a separate app. To change which projects the agent works on, switch between All projects and Only selected projects under Your organization > Administration > AI capabilities > Remediation Agent. To change repository-level access, update the personal access token or organization binding in Azure DevOps. See Azure DevOps project binding.
Disable or suspend agent access
A SonarQube Cloud Administrator can disable the agent for any platform: navigate to Your organization > Administration > AI capabilities > Remediation Agent > Enable agent and unselect the remediation type you want to suspend. After you select Save, the agent won't be triggered.
On GitHub, you can also suspend or uninstall the SonarQube Agent app completely. Navigate in GitHub to Your GitHub organization > Third-party Access > GitHub Apps > SonarQube Agent > Danger zone and select Suspend or Uninstall.
Suspend will block the agent's access to your repositories. This is the easiest way to restart the agent when you're ready.
If you select and confirm Uninstall, the SonarQube Agent will be removed from all of your repositories and from your SonarQube Cloud organization. The agent's activity will remain in your PR history, but if you want to use the agent again, you must return to Enable your agent.
On Azure DevOps, there's no app to suspend or uninstall. Disable the agent in SonarQube Cloud as described above, or revoke or rescope the personal access token in Azure DevOps to remove access.
Agent behavior
The SonarQube Remediation Agent proposes fixes in four ways: automatically on a schedule, for issues you assign from your backlog, for new issues in a pull request when its quality gate fails, and by retrying after CI failures on its own PRs.
Automated backlog remediation: The agent runs on a schedule you set, automatically proposing fixes for eligible issues in your main branch without manual assignment. For configuration details, see Backlog fix suggestions.
Manual backlog remediation: Select issues from your main branch and assign them to the agent. It opens a new pull request in your repository and groups the fixes you assign by rule key and file type. For details, see Backlog fix suggestions.
Pull request remediation (GitHub only): When your quality gate fails during PR analysis, the Quality Gate failed comment includes a Fix automatically checkbox. Select it to trigger the agent, which generates fixes and opens a separate PR targeting your branch. Its behavior and how to engage with it are described on Pull request fix suggestions.
CI/CD failure recovery (GitHub Actions only): If CI fails on an agent-created PR, the agent automatically reads the build logs, pushes a new commit to address the failures, and waits for CI to run again. The agent retries up to three times. If CI passes, the PR is ready for your review. If CI still fails after three attempts, the agent stops and leaves the PR open for you to fix manually. Recovery applies to PRs created from both pull request remediation and backlog remediation flows.
Note: CI/CD failure recovery works only for GitHub Actions workflows. The agent detects CI failures from any provider, but can only read build logs through the GitHub API, which exposes logs for GitHub Actions jobs only.
Unsupported rules
A small number of rules aren't supported because they're too complex for an LLM to solve.
Unsupported C# rules
csharpsquid:S1133
csharpsquid:S1134
csharpsquid:S1135
csharpsquid:S1144
csharpsquid:S3776
Unsupported Java rules
java:S120
java:S1133
java:S1134
java:S1135
java:S1144
java:S1228
java:S3776
Unsupported JavaScript rules
javascript:S1134
javascript:S1135
javascript:S1144
javascript:S1874
javascript:S3776
Unsupported Python rules
python:S1134
python:S1135
python:S1144
python:S3776
Unsupported TypeScript rules
typescript:S1134
typescript:S1135
typescript:S1144
typescript:S1874
typescript:S3776
Secrets rules
All Secrets rules are supported
Last updated
Was this helpful?