Branch analysis

Branch analysis in SonarQube Cloud lets you analyze branches of your project other than pull request branches and the main branch.

What is branch analysis for?

In most projects, SonarQube Cloud is configured to do two kinds of analyses:

• Main branch analysis: This occurs every time a change is pushed to the main branch. The analysis is done on the current state of the main branch, that is, the state recorded in the HEAD commit of the main branch, with a special focus on new code. The results of this analysis track the quality of the whole project and are used (via the quality gate) to ensure that the project is always in a releasable state.
• Pull request analysis: This occurs when a pull request is opened and every time a change is pushed to the pull request branch. Analysis results only include issues that have been introduced by the pull request itself. A quality gate on the pull request uses these results to ensure that the code changes introduced are always clean.

Branch analysis, in contrast, allows you to trigger an analysis on a push to any specified branch (not just the main branch) without involving pull requests. This capability can be useful in the following situations:

• If your project has long-living branches other than the main branch that you want to analyze. One use-case is having branches for older versions of your software that you still periodically update with critical fixes. Another is having separate branches for development and production in your project.
• If you use short-lived branches (for example, “feature” branches) to introduce changes to your main branch but do not use them with a pull request mechanism in a supported CI.

To support these use-cases, SonarQube Cloud lets you specify whether a branch is short- or long-lived using a naming convention. Based on this distinction, it will then analyze the two types of branches differently. For full details on setting up branch analysis and how it works, see Branch analysis setup. But first, an understanding of the results of the branch analysis will help.

In the SonarQube Cloud Free plan, branch analysis is available only on the main branch. Please see the Comparison table on the Subscription plans for plan details.

Branch analysis results

Assuming that you have set up your branch analysis properly, every time you push to the branch in question, SonarQube Cloud will analyze and report the result in the SonarQube Cloud interface. To see the analysis result, go to the project and select Branches from the left menu sidebar.

This view displays the main branch, as well as any other long-lived or short-lived branches that have been analyzed. It does not include branches that have been used for pull requests.

As we can see here, the view is organized into long-lived branches and short-lived branches.

SonarQube Cloud knows which is which based on the naming convention mentioned above. In this case, branch-a is considered a long-lived branch because its name matches the pattern (branch|release)-.* and the short branch is considered a short-lived branch because its name does not. The main branch (here named master) is always considered a long-lived branch.

Short-lived branch analysis

If you click on a short-lived branch, you will be taken to the short-lived branch analysis page:

You will notice that it is very similar to the Pull Requests analysis page. This is because it is based on the same principles. Like pull request analysis, short-lived branch analysis has two significant features:

• Short-lived branch analysis only reports issues that were introduced by the branch itself. When SonarQube Cloud analyzes a short-lived branch B with target branch T it scans the HEAD commit of B and compares the result with the most recent scan of T. Only issues that appear in B but not in T are reported in the analysis results. In cases where T includes new issues added since the most recent scan (in other words, the scan is outdated) those additional issues will appear as part of the short-lived branch analysis, even though they were not introduced by that branch. To understand how the target branch is determined see the Branch analysis setup page.
• The quality gate for the short-lived branch is computed based on this analysis. The quality gate used is the one set at the project level, however, only the conditions on new code within the quality gate are applied.

When selecting a Short-lived branch from the list of branches, you can see that on the Summary tab, the quality gate and the six quality metrics are displayed. In addition, the other tabs, Issues, Security Hotspots, Measures, and Code let you see more details about the analysis.

Long-lived branch analysis

If you select a branch from the Long-lived branches list you will be taken to the Summary page for that branch, much like we described above for the Short-lived branches:

As you can see, this page is very similar to the Main Branch analysis page. Again, this is because it is based on the same principles:

• At the top of the branches page, the quality gate shows the "releasability" status of the long-lived branch. It answers the question "Can I release this branch today?"
• There are two tabs: One for New Code and one for Overall Code, just as in the Main Branch view.
• The metrics displayed and the tabs available are identical to those found on the main branch analysis page, except that they apply to this long-lived branch.

See the Main branch analysis page for details about working with the Main Branch.

Incremental analysis

Some analyzers use the analysis cache mechanism to shorten the branch analysis.