> 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-cloud/administering-sonarcloud/ai-features/administer-remediation-agent.md). # Administer the Remediation Agent Enable the SonarQube Remediation Agent for your organization, add an LLM provider key, and control which repositories and projects it works on. 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. As an organization admin, use this page to enable the agent, manage repository access, and configure fixes for GitHub, GitLab, or Azure DevOps projects. To learn how the agent works, 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. The Remediation Agent requires a separate subscription to your SonarQube Cloud Team (annual) or Enterprise plan. To trial or purchase the Remediation Agent, contact [our Sales team](https://www.sonarsource.com/products/sonarqube/contact-sales/). ## Supported DevOps platforms, languages, and issues * The SonarQube Remediation Agent, when enabled, can make automated and manual backlog fix suggestions on private projects bound to GitHub, GitLab, or Azure DevOps. It can make fix suggestions in new pull requests on private GitHub-bound projects and merge requests on private GitLab-bound projects. * Pull request remediation, available for GitHub- and GitLab-bound projects, 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, PHP, and Python code. The agent can suggest fixes for secrets detected in your code. * The agent can suggest fixes for eligible [Hunter Agent findings](/sonarqube-cloud/managing-your-projects/issues/with-ai-features/hunter-agent-findings.md) in your main branch. * The agent can fix dependency vulnerabilities found by Software Composition Analysis (SCA). See [Reviewing and fixing dependency risks](/sonarqube-cloud/advanced-security/reviewing-and-fixing-dependency-risks.md) for details. ## Requirements and limitations * Analysis must be enabled on your repository, either automatic analysis or CI-based analysis. * Your GitHub, GitLab, or Azure DevOps organization and repository must be bound to your SonarQube Cloud organization and project. 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 five 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. {% hint style="warning" %} The supported-language restriction applies to static analysis issues. Hunter Agent findings are eligible regardless of language, subject to the other Remediation Agent eligibility requirements. 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. {% endhint %} ## 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. ## Enable your agent You must be an organization admin in SonarQube Cloud. Before you connect the agent, bind your project to its GitHub, GitLab, 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). ### GitLab: reuse your platform connection The agent uses the GitLab personal access token (PAT) you entered when you imported your GitLab group into SonarQube Cloud. There’s no separate app to install. Before you start, make sure: * Your organization has a Remediation Agent subscription * Your private GitLab.com project is imported into SonarQube Cloud and has been analyzed * The PAT has not expired or been revoked, has the `api` scope, and belongs to an account with at least the **Maintainer** role on the GitLab projects where the agent will run For import and binding instructions, see [Importing a GitLab group](/sonarqube-cloud/administering-sonarcloud/managing-organization/creating-organization/importing-gitlab-group.md) and [Configuring GitLab project binding](/sonarqube-cloud/managing-your-projects/administering-your-projects/devops-platform-integration/gitlab.md). For token permissions, see [GitLab access token scopes](https://docs.gitlab.com/security/tokens/access_token_scopes/). To enable the agent: 1. Go to *Your organization* > **Administration** > **AI capabilities** > **Remediation Agent**. 2. Under **Choose your key**, select your LLM provider key. If no key is available, [add a provider key](#add-a-provider-key), then return to select it. 3. Under **Enable agent**, enable **Manual backlog remediation** to assign issues from your main branch. Enable **Pull request remediation** to request fixes for issues in merge requests. 4. Review **Automated backlog remediation**. Turn it off if you want only on-demand fixes, or configure its schedule and projects as described in [Automated backlog remediation](/sonarqube-cloud/managing-your-projects/issues/with-ai-features/backlog-fix-suggestions.md#automated-backlog-remediation). 5. Select **Save** after changing the settings. After saving, [verify your GitLab setup](#verify-your-gitlab-setup). {% hint style="info" %} The Remediation Agent supports GitLab.com. Support for self-managed GitLab instances is not generally available. {% endhint %} #### Verify your GitLab setup With **Manual backlog remediation** enabled for your organization, start with one eligible backlog issue: 1. Open the project's **Issues** page and select its main branch. 2. Use **Fixable by Agent** to find eligible issues. Select one issue, then select **Fix with Agent**. If no eligible issues are available, use another analyzed project where the agent is enabled. 3. Open the project's **Agent activity** page. Confirm that a run appears, then check its outcome when it finishes. 4. If the agent produces a fix, open the linked merge request in GitLab. Check that it targets the project's main branch and contains the proposed change for the issue you selected. Review the change before merging it, or close the merge request if you do not want to apply the test fix. A run appearing in **Agent activity** confirms that SonarQube Cloud accepted the request. A merge request with a proposed fix confirms that the agent could read the repository and create a change. The agent might not find a fix for every eligible issue; a run without a fix does not by itself mean setup failed. To verify scheduled fixes, wait for the next configured run and check **Agent activity**. If no run appears, check that the selected projects have eligible issues, then check the schedule's time zone, project-level overrides, and **Pause when open PRs reach** limit. For merge request fixes, follow [Trigger fixes for a GitLab merge request](/sonarqube-cloud/managing-your-projects/issues/with-ai-features/pull-request-fix-suggestions.md#trigger-fixes-for-a-gitlab-merge-request). If a run fails, check that your GitLab PAT is valid and still has access to the project, and that your selected LLM provider key is valid. See [Manage agent access](#manage-agent-access) and [Manage and delete keys](#manage-and-delete-keys). ### Select flows and projects Under **Enable agent**, use **Manual backlog remediation** to control whether you can assign issues with **Fix with Agent** on the **Issues** page. For GitHub and GitLab, use **Pull request remediation** to control fixes for pull requests or merge requests. To schedule backlog fixes, select **Automated backlog remediation** at the bottom of the **Enable agent** list. Set the frequency (daily or weekly), the time, and the time zone 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**. Choose **All projects** or **Only selected projects** to control which projects are included in scheduled runs. Project admins can 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. {% hint style="info" %} You choose the provider, not the model. SonarQube Cloud uses Claude Opus 4.6 for Anthropic and GPT-5.5 for OpenAI. {% endhint %} ### 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 choose projects for scheduled fixes, 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). ### GitLab To choose projects for scheduled fixes, select **All projects** or **Only selected projects** under *Your organization* > **Administration** > **AI capabilities** > **Remediation Agent**. To change repository access, update the PAT used for your GitLab connection or the project permissions of the account that owns the token. Merge requests created by the agent appear under that GitLab account. ### 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 and GitLab, there’s no app to suspend or uninstall. Disable the agent in SonarQube Cloud using the steps in this section. To remove access through your GitLab or Azure DevOps connection, revoke its PAT or change the token's permissions. Revoking the PAT also affects other SonarQube Cloud features that use that connection. ## 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](/sonarqube-cloud/managing-your-projects/issues/with-ai-features/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. Each Hunter Agent finding is processed separately, with its own pull or merge request, if a fix is available. For details, see [Backlog fix suggestions](/sonarqube-cloud/managing-your-projects/issues/with-ai-features/backlog-fix-suggestions.md). * **Pull request remediation** (GitHub and GitLab): When your quality gate fails during pull request analysis, trigger the agent from the **Fix automatically** checkbox in the GitHub comment or from **Fix with Agent** in SonarQube Cloud for a GitLab merge request. The agent opens a separate pull request or merge request targeting your branch. Its behavior and how to engage with it are described on [Pull request fix suggestions](/sonarqube-cloud/managing-your-projects/issues/with-ai-features/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.

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 PHP rules php:S1134 php:S1135 php:S1144 ### 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.sonarsource.com/sonarqube-cloud/administering-sonarcloud/ai-features/administer-remediation-agent.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.