Pull request fix suggestions

Understand how the SonarQube Remediation Agent behaves in your pull request and how to engage with it when your quality gate fails.

This page helps you understand the behavior of the SonarQube Remediation Agent and provides additional information about engaging with the agent during the review process of your pull request. To learn how the agent works, see Remediation Agent in the Agent Centric Development Cycle documentation.

For AI-powered pull request review, we recommend Gitar, a separate Sonar product. To get started, see the Gitar quickstart.

Pull request remediation is currently available for GitHub-bound projects only. For Azure DevOps-bound projects, see Backlog fix suggestions.

Prerequisites

An organization admin must enable the SonarQube Remediation Agent and add an LLM provider key for your organization before the agent can run. See Enable your agent and Configure your LLM provider key.

Activate the Remediation Agent

When the SonarQube Remediation Agent is activated for Pull request fixes as described on the Administer the Remediation Agent page, its activity can be reviewed in SonarQube Cloud and the agent can be engaged in GitHub on your open pull request (PR). When your quality gate fails during a PR analysis, the Quality Gate failed comment posted by the sonarqubecloud GitHub App contains a Remediation Agent ready section. This section includes a Fix automatically checkbox with the subtitle Creates a separate PR with fixes for eligible issues.

Select the Fix automatically checkbox to trigger the agent. The Quality Gate failed comment updates to show Remediation Agent Launched! with a link to follow progress, and a new Remediation Agent Summary comment appears stating Generating fix suggestions for your pull request. This comment will be updated automatically. If a fix or fixes are available, the SonarQube Remediation Agent suggests changes in a new PR targeting your branch. This PR contains a commit or series of commits along with information about each issue and why the changes were made.

The Quality Gate failed comment contains a Remediation Agent ready section with a Fix automatically checkbox.

After selecting Fix automatically, the Quality Gate failed comment updates to show Remediation Agent Launched.

After selecting Fix automatically, a record of the agent's activity shows up in SonarQube Cloud on your project's Agent activity page; see Agent activity for details.

When additional commits are added to your PR and the quality gate again fails, a new agent will be triggered, repeating the process. Issues will be fixed once you review and merge the agent's changes into your active branch.

Engage with the agent

After selecting Fix automatically, a single Remediation Agent Summary comment is created on your open pull request explaining the agent's progress and suggestions. The summary first appears stating Generating fix suggestions for your pull request. This comment will be updated automatically. It then progresses through the following states as the agent works:

• In queue—the request is accepted and waiting for a worker.
• Analyzing issues... (X of Y completed)—a progress bar shows counts for In progress, In queue, Generating, and Completed.
• Completed—the Quality Gate failed comment updates to show Fixes are ready in agent created PR #XXX, and the Summary comment shows To review: Fixes are ready for X of Y issues found. along with Save time: Applying these fixes could save you an estimated NN minutes.

While the agent is working, the Remediation Agent Summary comment shows a progress bar with counts for In queue, Generating, and Completed.

When the agent finishes, the Summary comment briefly explains the issue types it addressed and links to a new PR for your review. The following shows the completed Remediation Agent Summary:

• The status of your quality gate is shown on the activity history of your PR. The next action item in your history should be the Remediation Agent Summary; if it doesn't show up or isn't updating its status, try refreshing your page.
• Select the Suggested fixes (X) collapsible to reveal the list of fixes provided by the agent. The summary provides information about:

  • Quality: each issue's software quality
  • Issue: the issue's rule description and a link to the issue as found in the SonarQube Cloud pull request analysis
• If the agent can't provide a fix suggestion, Issues requiring manual fix is listed. When expanded, you see the issue's rule description and a link to the issue in the SonarQube Cloud pull request analysis. See the page about using SonarQube for IDE and connected mode to learn how to find and fix an issue in your IDE.
• Agent created PR #XXX provides a link to a new PR created by the SonarQube Remediation Agent, on your branch. This PR contains a list of Fixed Issues including rule descriptions and a series of commits organized by issue, ready for you to review. See Review agent fix suggestions. A link to the same PR is also available on the Agent activity page.

The completed Remediation Agent Summary comment shows save-time guidance and a Suggested fixes collapsible.

Review agent fix suggestions

Open the agent's PR (linked from the Agent created PR #XXX entry in the previous section) to review fix suggestions before merging them into your original PR.

The Fixed Issues summary on the agent's pull request lists each issue's rule number, title, quality, description, along with a link to the issue in SonarQube Cloud. The PR summary is followed by a list of commits where the change summary is stacked and sorted by issue keys.

• The SonarQube Remediation Agent creates a new PR targeting your branch.
• A link to your project in SonarQube Cloud is provided.
• The PR summary provides a list of Fixed Issues as an inventory of fixes in this PR. Expand an issue to see its rule description, information about Why this is an issue, and a quick diff view showing What changed in this PR.
• The View issue link takes you to the issue in SonarQube Cloud.
• The SonarQube Remediation Agent is listed as the commit author.
• The agent's comments are condensed in the commit message and the change summary is stacked and sorted by issue key.
• A new PR analysis will be run automatically to check the agent's fixes against your quality standards.

Each issue fixed by the SonarQube Remediation Agent will have information to help you review what is changed in the PR.

Once reviewed and merged, the commits will be added to your original PR. These new commits will trigger a new Pull request analysis and the cycle will repeat until your quality gate passes your quality standards.

CI/CD failure recovery

If CI fails on the agent's PR, the agent automatically reads the build logs, pushes a new commit to address the failures, and waits for CI to run again. You can follow each attempt in the agent's PR description. CI/CD failure recovery doesn't create a new entry on the Agent activity page. Progress is tracked within the agent's existing PR.

The agent retries up to three times. If CI still fails after three attempts, the agent stops and leaves the PR open for you to fix manually.

CI/CD failure recovery works only for GitHub Actions workflows. If your CI uses another provider, SonarQube Cloud detects the failure but can't retrieve the logs needed to generate a fix.