> 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/agent-centric-development-cycle/solve/solve-issues/administer-remediation-agent.md). # Administer 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](https://docs.sonarsource.com/sonarqube-cloud/advanced-security/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](#configure-your-llm-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](https://www.sonarsource.com/legal/early-access/) in our [Legal documentation](https://www.sonarsource.com/legal/). ## 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](https://github.com/apps/sonarqube-agent). 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](/sonarqube-cloud/administering-sonarcloud/managing-organization/creating-organization/importing-azure-devops-organization.md#create-pat) and [Azure DevOps project binding](/sonarqube-cloud/managing-your-projects/administering-your-projects/devops-platform-integration/azure-devops.md). ### 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: 1. Select **Add key**. 2. Choose a provider: **OpenAI** or **Anthropic**. 3. Enter the API key from your provider account. 4. Enter a name to identify the key in SonarQube Cloud. 5. 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](/sonarqube-cloud/managing-your-projects/administering-your-projects/devops-platform-integration/azure-devops.md). ### 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](#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](/agent-centric-development-cycle/solve/solve-issues/backlog-fix-suggestions.md#automated-backlog-remediation). * **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](/agent-centric-development-cycle/solve/solve-issues/backlog-fix-suggestions.md). * **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](/agent-centric-development-cycle/solve/solve-issues/pull-request-fix-suggestions.md). * **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 --- # 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/agent-centric-development-cycle/solve/solve-issues/administer-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.