Remediation Agent

Set up and use the SonarQube Remediation Agent on SonarQube Server 2026.5, from deploying the agent to reviewing the pull requests it opens.

The SonarQube Remediation Agent proposes fixes for the issues in your backlog, and for the issues in a pull request when its quality gate fails. You can assign issues to it yourself, or let it work through your backlog on a schedule. Either way, it generates the changes in the background and opens a pull request in your repository for you to review and approve. You stay in control, because the agent never merges anything.

Deploying the agent always deploys the Vortex analysis component it depends on. This is because the agent uses Vortex analysis to verify its fix suggestions and produce better results, even if you do not have a Vortex subscription. That subscription is for your developers' own coding agents, reached through the SonarQube CLI, a SonarQube agent plugin, or a locally running SonarQube MCP Server. See Sonar Vortex. For the component itself, see Vortex analysis.

To learn how the agent generates and verifies fix suggestions, see Remediation Agent in the Agent Centric Development Cycle documentation. For subscription and consumption details, see Subscription and consumption.

Supported languages

The agent can suggest fixes for issues found in C#, Java, JavaScript/TypeScript, and Python code. A small number of rules in these languages aren't supported because they're too complex for an LLM to solve; see Unsupported rules.

Subscription and consumption

Subscription requirements

The Remediation Agent requires a separate subscription alongside your SonarQube Server Enterprise or Data Center edition. To trial or purchase Remediation Agent, contact our Sales team. See the Sonar product subscriptions page for details about adding a subscription. Your SonarQube Server license must be activated through LicenseSpring, either online or offline; the Remediation Agent is not available with a server ID-based license.

Your Remediation Agent subscription supports overage, letting you keep fixing issues past your base allowance for an extra monthly cap you set yourself. See the Overage activation page to activate it. Overage requires online license connectivity and is not available on a server ID-based license. Your base allowance and overage cap are both measured in suggestions.

What counts as a suggestion

A suggestion is the unit the Remediation Agent consumes to fix issues. Suggestions are drawn from your base allowance first and, if overage is active, from your overage cap:

• A fix counts as one suggestion once the agent delivers it in the pull request it opens, regardless of whether the job started from an assignment, a scheduled run, or a failing quality gate on a pull request.
• A single pull request can contain fixes for multiple issues. Each fix counts as its own suggestion, whether or not you merge the pull request.

See the Sonar product subscriptions page to manage your suggestion usage.

Setup overview

Setup spans several roles. Complete the steps in order.

Step	Task	Who does it	Where
1	Add the Remediation Agent to your license.	Instance administrator	License management
2	Deploy the agent on your own infrastructure.	System administrator	Deploying AI agents
3	Add an LLM provider, then choose a model for the agent.	Instance administrator	AI Capabilities > LLM Providers (see LLM providers), then Enabling the agent
4	Give the agent write access to your repositories.	DevOps platform administrator	DevOps platform permissions
5	Enable the agent, and set the automated schedule if you want scheduled runs.	Instance administrator	Enabling the agent
6	Adjust the schedule for a single project.	Project administrator	Remediation Agent

Steps 1 to 5 are all required. Step 6 is optional.

Before you start, check what the agent needs from your projects in Prerequisites.

Prerequisites

• The agent is deployed on your own infrastructure, along with the Agent Orchestrator, shared storage, and Vortex analysis. The agent cannot run until these are in place, even once it's licensed and enabled. See Deploying AI agents.
• You have an active subscription for the Remediation Agent, and an LLM provider and a model are configured. For the full list of steps and who's responsible for each, see Setup overview. Until you save a provider and a model, you cannot enable Manual backlog remediation or Automated backlog remediation. See LLM providers.
• The agent supports the claude-opus-4-6 and gpt-5.5 models. Select the provider-specific identifier or deployment for one of those models when you configure a provider for the agent.
• Each project you want the agent to work on is bound to a repository on your DevOps platform. The agent clones the repository to generate fixes and opens a pull request with the result. It cannot run on a project that isn't bound. The agent supports GitHub, GitLab, and Azure DevOps. See DevOps platform integration for details.
• You've analyzed the project, so the agent has issues to work from.

DevOps platform permissions

The Remediation Agent writes to your repository. It clones your code, pushes a branch, and opens a pull request for you to review. Each of those actions needs write access.

Importing repositories and reporting the quality gate status need only read access, so that's all most existing integrations grant. Add write access before you enable the agent.

What to grant

Platform	Permissions to grant	Allows the agent to
GitHub	Contents: Read & Write Pull requests: Read & Write	Clone the repository, push a branch, open a pull request, and assign a reviewer.
GitLab	api, read_repository, write_repository	Clone the repository, push a branch, open a merge request, and assign an approver.
Azure DevOps	Code > Read & write Identity > Read	Clone the repository, push a branch, open a pull request, and assign a reviewer.

On Azure DevOps, Identity > Read lets the agent assign a reviewer to the pull request. Without it, the pull request opens with no reviewer assigned.

On GitLab and Azure DevOps, the account's role also matters, separately from the token's scope. Each platform's procedure below covers the role needed.

The agent does not merge its pull requests. Approving and merging stays with your team.

Reviewer assignment support

The agent assigns a reviewer or approver on GitHub, GitLab, and Azure DevOps whenever your permissions allow it.

On GitLab, reviewer assignment requires GitLab 16.3 or later. Earlier versions do not support the API call the agent uses to select a reviewer.

Granting the permissions

Follow the procedure for your platform, then confirm the result in Checking the permissions.

GitHub

What you do next depends on how you created the GitHub App.

If you used Create GitHub App, the app already requests Contents: Read & Write and Pull requests: Read & Write, so you do not need to change anything.

If you registered the app manually, or you're reusing an app that predates the agent, raise the permissions in GitHub:

1. In GitHub, go to Settings > Developer Settings > GitHub Apps, then select your SonarQube Server app.
2. Select Permissions & events.
3. Under Repository permissions, set Contents to Read & Write.
4. Confirm that Pull requests is also set to Read & Write.
5. Save your changes.
6. Have an organization owner approve the new permissions for every organization where the app is installed. GitHub emails the organization's administrators to request approval.

Step 6 is easy to miss. Raising the permissions on the app is not enough on its own: until an owner approves the change, the installation keeps its previous access and the agent cannot push, even though GitHub shows Read & Write on the app.

The agent also uses Checks: Read & Write and Metadata: Read-only, which the SonarQube GitHub App already needs for analysis.

For the full permission set, see Setting up a GitHub App.

GitLab

On GitLab, use a personal access token. Do not use a project access token: the agent is unavailable for any project bound with one. If you already use GitLab, check which kind of token your configuration holds before you enable the agent.

1. In GitLab, sign in as the account SonarQube Server uses for the integration.
2. Create a personal access token with the api, read_repository, and write_repository scopes. When GitLab offers a choice of token type, select the legacy personal access token.
3. Confirm the account has at least the Maintainer role in the projects the agent works on. Reporter or Developer permissions are not enough when the project's protected-branch or push rules restrict the branches the agent creates.
4. In SonarQube Server, go to Administration > Configuration > General settings > DevOps platform integrations and select the GitLab tab.
5. Enter the token in your GitLab configuration record and save.

GitLab has no scope narrower than api for opening merge requests, so the token carries more access than the agent uses. Use a dedicated GitLab account for the integration.

For the rest of the setup, see Binding to GitLab.

Azure DevOps

1. In Azure DevOps, go to User settings > Personal access tokens for the account SonarQube Server uses.
2. Create a token, or edit your existing one, with at least the Code > Read & write and Identity > Read scopes.
3. Add the account to the Contributors security group, so it can push a branch and open a pull request.
4. In SonarQube Server, go to Administration > Configuration > General settings > DevOps platform integrations and select the Azure DevOps tab.
5. Enter the token in Personal Access Token and save.

Azure DevOps PATs expire, and Azure DevOps stops a PAT when the account has not signed in for 30 days. The agent stops working when that happens. See the PAT failure points in Preparing the integration.

For the rest of the setup, see Binding to Azure DevOps.

Checking the permissions

SonarQube Server validates the agent's repository access and reports the result in two places: on Administration > Configuration > AI capabilities > Remediation Agent, and on Administration > Configuration > General settings > DevOps platform integrations.

Select Check configuration after you change anything on your DevOps platform.

If the check reports that a permission is missing, grant it and select Check configuration again. If it reports that it could not verify your permissions, confirm the token is valid and has not expired, and that SonarQube Server can reach your platform.

On Azure DevOps, the check confirms only that SonarQube Server can reach your organization; it does not confirm the permissions. Verify the Code > Read & write and Identity > Read scopes yourself in Azure DevOps, then confirm the setup once the agent is enabled by checking that it opens a pull request.

After the check passes, continue to Enabling the agent.

Enabling the agent

An instance administrator enables the agent and chooses which remediation flows are available. The two flows are independent:

• Manual backlog remediation: reduce technical debt by selecting issues from a project's issues list and letting the agent propose fixes in a pull request.
• Automated backlog remediation: reduce technical debt by automatically fixing high-priority issues on your main branch on a schedule.

With repository access in place, enable the agent:

1. Go to Administration > Configuration > AI capabilities > Remediation Agent.
2. Turn on Manual backlog remediation to let your team assign issues to the agent from the project's issues list.
3. Turn on Automated backlog remediation to have the agent propose fixes on a schedule. The schedule settings appear when you turn this on.

Turning off Automated backlog remediation hides its schedule settings and stops scheduled runs. Manual assignment is unaffected.

Configuring the automated schedule

Under Run schedule, set when the agent runs:

Setting	Description
Frequency	Daily or Weekly.
Day of week	The day the agent runs. Available when the frequency is Weekly.
Hour	The hour the run starts.
Timezone	The timezone that applies to the run time, for example Europe/Paris (UTC+2).

To cap how many pull requests the agent keeps open, set a value under Pause when open PRs reach, or select Don't pause to leave the number uncapped. Only the pull requests opened by scheduled runs count toward the limit. Pull requests from manual assignment or any other source do not count.

The agent checks the number at the start of each scheduled run and skips the run when the limit is reached. It resumes on its own at the next scheduled run, once you've merged or closed enough of its pull requests.

A summary confirms the schedule you've set, including the next run time. Each run opens one pull request for up to five issues in every selected repository.

Select Save to apply your changes. Schedule settings take effect only after you save.

Choosing which projects use automated remediation

Under Choose which projects should have automated remediation, select one of:

• All projects: enable on all existing and future projects.
• Only selected projects: enable on the projects you pick. Projects you create later are not included automatically.

Project administrators can override the instance schedule for their own project. See Remediation Agent in the Project administration documentation.

Using the agent

After setup is complete, the agent proposes fixes for the issues assigned to it and for the issues it picks up on its automated schedule. Developers follow its jobs and review the pull requests it opens. You don't need a dedicated permission to assign issues.

See Backlog fix suggestions.

The agent can also fix issues in a pull request when its quality gate fails, for projects bound to GitHub, GitLab, or Azure DevOps. See Pull request fix suggestions.

To understand what counts as one suggestion, see What counts as a suggestion.

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

Unsupported Java rules

java:S1133

java:S1134

java:S1135

java:S1144

java:S1228

Unsupported JavaScript rules

javascript:S1134

javascript:S1135

javascript:S1144

javascript:S1874

Unsupported Python rules

python:S1134

python:S1135

python:S1144

Unsupported TypeScript rules

typescript:S1134

typescript:S1135

typescript:S1144

typescript:S1874

Related pages

• Remediation Agent

• Remediation Agent

• Pull request fix suggestions