Agents in your GitHub pull request

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.

The SonarQube Remediation agent

The SonarQube Remediation Agent is a Beta feature available with Enterprise plan accounts. It is free during the beta phase and will be a paid feature when it moves to General Availability. To learn more about the terms & conditions, please see our legal page about features in Early Access.

If your SonarQube Cloud organization is not on an Enterprise plan, please see the Getting started with Enterprise pages to get the process started.

Once the SonarQube Remediation agent is activated as described on the SonarQube Remediation agent page, it's activity can be reviewed in SonarQube Cloud and the agent can be engaged in GitHub on your open PR.

The agent is triggered when your quality gate fails during the pull request (PR) analysis. If you have additional commits on the PR that retrigger the quality gate failure, you will trigger a new agent and only engage with the most recent agent called.

Once active, the SonarQube Remediation agent automatically generates commit suggestions for new issues introduced in the PR. It only offers fix suggestions for issues in the PR within which the agent is was triggered.

Agent behavior

After your SonarQube Cloud administrator has completed the steps laid out in the Enable your agent article, navigate to Your SonarQube Cloud Project > Agent activity to view your remediation agent’s activity. The Agent activity page provides basic information and hyperlinks to:

1. The GitHub PR where the agent exists.

2. The PR summary for the relevant pull request. See the Pull request analysis page for information about Understanding your pull request analysis.

3. A timestamp for the recorded activity.

Engage with the agent

A single Remediation Agent Summary will be created on your pull request explaining the agent’s suggestions, and a unique Agent Fix (Issue X of Y) commit suggestion for each issue will be created for review by a developer. The summary provides an explanation about each fix suggestion, including links to the issue description, type, severity, and estimated effort required to fix (where applicable). See the diagram below for a more detailed explaination:

1. The status of your quality gate will be shown on the activity history of our PR. The next action item in your history should be the Remediation Agent summary; if it doesn't show up or isn't udating its status, try refreshing your page.

2. Select the Suggested fixes collapsible to reveal the list of fixes provided by the agent. The summary page provides information about:

   • Quality: each issue's Software qualities

   • Issue: the issues's rule description and a link to the issue as found in the SonarQube Cloud Pull request analysis

   • Status: the state of each issue's resolution in relation to the agent's activity

3. Each fix suggestion provides the issue's rule description and the accompanying information as found with every SonarQube rule.

4. Select View fix to jump to a unique comment in your PR history. There, you can review the fix in more detail and if approved, commit the fix as a change. See Review agent fix suggestions for more information.

5. If the agent can't provide a fix suggestion, the issue will be listed here. Depending on the number of issues and the parameters of your quality gate, you may need to fix these issues in the IDE before being able to merge your PR. See the page about using SonarQube for IDE and connected mode, if needed.

Review agent fix suggestions

If in point 4 above, you selected View fix, you'll arrive at a unique comment designed for reviewing your specific issue.

Each issue has its own comment that includes a dif view of the suggested change along with an explanation about the fix suggestion. Additional information includes links to the issue description, type, severity, and an estimated effort required to fix the issue (where applicable).

1. Use this information to find your issue's location in your code.

2. A dif view is provided so you can see what will be changed if you choose to Select fix (see number 4 below).

3. The suggestion details include an AI-generated explanation of what the code change is accomplishing.

4. Choosing Select fix means that you have reviewed the content and have marked the agent's fix suggestion to be commited to your PR. The fix suggestion will be added to a list that must be confirmed in the next step.

5. IMPORTANT: Select Commit changes only when you are ready to accept all of your selected fixes. Selecting the Commit changes checkbox applies all of the reviewed changes you accepted in point 4. Once selected, all of the changes will be applied to your code in a new commit.

The agent's commit

The SonarQube Remediation Agent will contain important information that you may want to reference later. Here's a list of the information that it includes:

• The fixes you reviewed and approved (when selecting Select fix) will be kept as hidden items in your PR history. The fix comment, as described in Review agent fix suggestions, will be updated to confirm that the fix suggestion was commited to your PR.

• All of the fixes that you select will be in the single commit with a unique reference number, and marked as co-authored by you and the sonarqube-agent [bot].

• The new commit will trigger another pull request analysis on SonarQube Cloud. The results of the analysis will determine what happens next in your PR:

  • If your quality gate passes, you can proceed with merging in accordance with your Branch protection rules.

  • If your quality gate fails, the SonarQube Remediation Agent will be retriggered, and you can restart the review process of its fix suggestion. The agent may take a few minutes to run depending on the complexity of your project. Refreshing the page in GitHub can help show the agent's most recent activity.