> 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/managing-your-projects/issues/with-ai-features/pull-request-fix-suggestions.md). # 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. Use the SonarQube Remediation Agent to request fixes for new issues in a GitHub pull request or GitLab merge request when its quality gate fails. 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. {% hint style="info" %} For AI-powered pull request review, we recommend [Gitar](https://docs.gitar.ai/introduction), a separate Sonar product. To get started, see the [Gitar quickstart](https://docs.gitar.ai/quickstart). {% endhint %} {% hint style="info" %} Pull request remediation is available for GitHub- and GitLab-bound projects. For GitLab, trigger the agent from SonarQube Cloud as described in [Trigger fixes for a GitLab merge request](#trigger-fixes-for-a-gitlab-merge-request). For Azure DevOps-bound projects, see [Backlog fix suggestions](/sonarqube-cloud/managing-your-projects/issues/with-ai-features/backlog-fix-suggestions.md). {% endhint %} ## 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](/sonarqube-cloud/administering-sonarcloud/ai-features/administer-remediation-agent.md#enable-your-agent) and [Configure your LLM provider key](/sonarqube-cloud/administering-sonarcloud/ai-features/administer-remediation-agent.md#configure-your-llm-provider-key). ## Activate the Remediation Agent ### Trigger fixes from GitHub When the SonarQube Remediation Agent is activated for **Pull request remediation** as described on the [Administer the Remediation Agent](/sonarqube-cloud/administering-sonarcloud/ai-features/administer-remediation-agent.md) 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.](https://2223713658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB4UT2GNiZKjtxFtcFAL7%2Fuploads%2Fgit-blob-cb75ad40eb0999e30e4bcae32ef69d7b01583803%2Fsonarqube-cloud-quality-gate-with-fix-automatically.png?alt=media) ![After selecting Fix automatically, the Quality Gate failed comment updates to show Remediation Agent Launched.](https://2223713658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB4UT2GNiZKjtxFtcFAL7%2Fuploads%2Fgit-blob-c41949ed6739f5beaefc13b459d66b5fcc091742%2Fsonarqube-cloud-remediation-agent-launched.png?alt=media) 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](/sonarqube-cloud/managing-your-projects/issues/with-ai-features.md#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. ### Trigger fixes for a GitLab merge request Ask your organization admin to enable **Pull request remediation** for your GitLab organization. For setup instructions, see [GitLab setup](/sonarqube-cloud/administering-sonarcloud/ai-features/administer-remediation-agent.md#gitlab-reuse-your-platform-connection). Before you start, make sure your merge request has been analyzed and its quality gate fails because of new issues in a supported language. See [Supported DevOps platforms, languages, and issues](/sonarqube-cloud/administering-sonarcloud/ai-features/administer-remediation-agent.md#supported-devops-platforms-languages-and-issues). To request and check fixes: 1. Open the project's **Summary** page in SonarQube Cloud and select the merge request. 2. Select **Fix with Agent** or **Fix all with Agent** in the Remediation Agent banner, depending on your view. 3. Open the project's **Agent activity** page. Check that the run appears, then wait for it to finish. If a fix is available, open the linked merge request in GitLab. 4. Check that the agent's merge request targets your original merge request's source branch, then review and merge the fixes. 5. Check the next SonarQube Cloud analysis of your original merge request. If analysis does not run automatically, run your usual merge request analysis again. Confirm that the targeted issues are resolved. Other unresolved issues or conditions can still cause the quality gate to fail. If **Fix with Agent** is missing, check that pull request remediation is enabled for your organization and the latest analysis has new issues the agent supports. The **Fix with Agent** option is unavailable when the merge request introduces more than 20 new issues. If a run fails, ask your organization admin to check the [GitLab connection and provider key](/sonarqube-cloud/administering-sonarcloud/ai-features/administer-remediation-agent.md#verify-your-gitlab-setup). GitLab merge request fixes are triggered from SonarQube Cloud. Follow progress in **Agent activity**; the GitHub comment workflow in [Engage with the agent](#engage-with-the-agent) applies to GitHub only. ## Engage with the agent The comment workflow in this section applies to GitHub. For GitLab, follow progress on the **Agent activity** page in SonarQube Cloud. 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.](https://2223713658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB4UT2GNiZKjtxFtcFAL7%2Fuploads%2Fgit-blob-f48c2c92398efe407565989f7ba8b15fe43ea68f%2Fsonarqube-cloud-remediation-agent-summary-progress.png?alt=media) 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](/sonarqube-cloud/standards/managing-rules/rules.md#software-qualities) * **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](/sonarqube-cloud/analyzing-source-code/connected-mode.md) 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](#review-agent-fix-suggestions). A link to the same PR is also available on the [Agent activity](/sonarqube-cloud/managing-your-projects/issues/with-ai-features.md#agent-activity) page. ![The completed Remediation Agent Summary comment shows save-time guidance and a Suggested fixes collapsible.](https://docs.sonarsource.com/~gitbook/image?url=https%3A%2F%2F2223713658-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FB4UT2GNiZKjtxFtcFAL7%252Fuploads%252FVQODfRc4Y0cMEy9sNI4N%252Fsonarqube-cloud-remediation-agent-summary-with-pr.png%3Falt%3Dmedia%26token%3D4b5eab68-ca8b-4080-840a-8af2494c8cb1\&width=768\&dpr=3\&quality=100\&sign=2af1d228\&sv=2) ## Review agent fix suggestions Open the agent's pull request or merge request from **Agent activity** in SonarQube Cloud to review the proposed fixes before merging them into your original branch. On GitHub, the **Agent created PR #XXX** entry in the summary comment also links to the fixes. 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. * On GitHub, 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.](https://docs.sonarsource.com/~gitbook/image?url=https%3A%2F%2F2223713658-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FB4UT2GNiZKjtxFtcFAL7%252Fuploads%252FlgyQ9BW4qXHZawHNutLX%252Fsonarqube-cloud-review-fixed-issues-in-pr.png%3Falt%3Dmedia%26token%3Dde7b55c1-84ce-466b-81b7-ec9a1c152dde\&width=768\&dpr=3\&quality=100\&sign=28ffbdff\&sv=2) Once reviewed and merged, the commits will be added to your original PR. These new commits will trigger a new [Pull request analysis](/sonarqube-cloud/analyzing-source-code/pull-request-analysis.md) 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. {% hint style="info" %} 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. {% endhint %} --- # 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/managing-your-projects/issues/with-ai-features/pull-request-fix-suggestions.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.