> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-server/instance-administration/ai-features/remediation-agent.md).
# Remediation Agent
Set up and use the SonarQube Remediation Agent on SonarQube Server, 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](/sonarqube-server/instance-administration/ai-features/sonar-vortex.md). For the component itself, see [Installation overview](/sonarqube-server/server-installation/ai-agents/installation-overview.md#vortex-analysis).
To learn how the agent generates and verifies fix suggestions, see [Remediation Agent](/agent-centric-development-cycle/in-your-long-living-branches-the-code-maintenance-loop/remediation-agent.md) in the Agent Centric Development Cycle documentation. For subscription and consumption details, see [#subscription-and-consumption](#subscription-and-consumption "mention").
## 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](#unsupported-rules "mention").
## Subscription and consumption
### Subscription requirements
The Remediation Agent requires a separate subscription alongside your SonarQube Server Enterprise or Data Center edition. See the [Sonar product subscriptions](/sonarqube-server/instance-administration/license-management/product-subscriptions.md) 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](/sonarqube-server/instance-administration/license-management/overage-activation.md) 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](/sonarqube-server/instance-administration/license-management/product-subscriptions.md) 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](/sonarqube-server/instance-administration/license-management.md) |
| 2 | Deploy the agent on your own infrastructure. | System administrator | [Deploying AI agents](/sonarqube-server/server-installation/ai-agents.md) |
| 3 | Add an LLM provider, then choose a model for the agent. | Instance administrator | **AI Capabilities** > **LLM Providers** (see [LLM providers](/sonarqube-server/instance-administration/ai-features/llm-providers.md)), then [#enabling-the-agent](#enabling-the-agent "mention") |
| 4 | Give the agent write access to your repositories. | DevOps platform administrator | [#devops-platform-permissions](#devops-platform-permissions "mention") |
| 5 | Enable the agent, and set the automated schedule if you want scheduled runs. | Instance administrator | [#enabling-the-agent](#enabling-the-agent "mention") |
| 6 | Adjust the schedule for a single project. | Project administrator | [Remediation Agent](/sonarqube-server/project-administration/ai-features/remediation-agent.md) |
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 "mention").
## 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](/sonarqube-server/server-installation/ai-agents.md).
* 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](#setup-overview "mention"). Until you save a provider and a model, you cannot enable **Manual backlog remediation** or **Automated backlog remediation**. See [LLM providers](/sonarqube-server/instance-administration/ai-features/llm-providers.md).
* 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](/sonarqube-server/instance-administration/devops-platforms.md) 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-permissions](#checking-permissions "mention").
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.
{% hint style="warning" %}
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.
{% endhint %}
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](/sonarqube-server/instance-administration/devops-platforms/github/setting-up-github-app.md).
GitLab
{% hint style="warning" %}
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.
{% endhint %}
1. In GitLab, sign in as the account SonarQube Server uses for the integration.
2. Create a [personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) 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](/sonarqube-server/instance-administration/devops-platforms/gitlab.md).
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.
{% hint style="info" %}
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 [Binding to Azure DevOps](/sonarqube-server/instance-administration/devops-platforms/azure-devops.md#preparing).
{% endhint %}
For the rest of the setup, see [Binding to Azure DevOps](/sonarqube-server/instance-administration/devops-platforms/azure-devops.md).
### 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 "mention").
## 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](/sonarqube-server/project-administration/ai-features/remediation-agent.md) 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](/sonarqube-server/user-guide/issues/with-ai-features/backlog-fix-suggestions.md).
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](/sonarqube-server/user-guide/issues/with-ai-features/pull-request-fix-suggestions.md).
To understand what counts as one suggestion, see [#what-counts-as-a-suggestion](#what-counts-as-a-suggestion "mention").
## 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](/agent-centric-development-cycle/in-your-long-living-branches-the-code-maintenance-loop/remediation-agent.md)
* [Remediation Agent](/sonarqube-server/project-administration/ai-features/remediation-agent.md)
* [Pull request fix suggestions](/sonarqube-server/user-guide/issues/with-ai-features/pull-request-fix-suggestions.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.sonarsource.com/sonarqube-server/instance-administration/ai-features/remediation-agent.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.