Branch analysis in SonarCloud lets you analyze branches of your project other than pull request branches and the main branch.
What is branch analysis for?
In most projects, SonarCloud 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
HEADcommit 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, SonarCloud 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.
Branch analysis results
Assuming that you have set up your branch analysis properly, every time you push to the branch in question, SonarCloud will analyze and report the result in the SonarCloud interface. To see the analysis result, go to the project and click on Branches.
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 In this case, there are two long-lived branches:
branch-1 and one short-lived branch,
SonarCloud knows which is which based on the naming convention mentioned above. In this case,
branch-1 is considered a long-lived branch because its name matches the pattern
shortbranch is considered a short-lived branch because its name does not. The main branch (here named
main) is always considered a long-lived branch.
Short-lived branch analysis
If you click on
shortbranch, you will be taken to the short-lived branch analysis page:
You will notice that it is very similar to the pull request 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 SonarCloud 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 Branch analysis setup.
- 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.
Above, you can see that on the Summary tab, the quality gate and the six quality metrics are displayed. In addition, the other tabs, Issues, Measures, and Code let you see more details about the analysis.
Long-lived branch analysis
If you click on
branch-1, you will be taken to the long-lived branch results page:
As you can see this page is very similar to the main 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 Main Branch Analysis for details.