Branch analysis

Branch analysis is available starting in Developer Edition.

Overview

With branch analysis, you can ensure that you're maintaining consistent code quality all the way down to the branch level of your projects.

Main branch

This is the default branch and typically corresponds to what's being developed for your next release. This branch is usually known within a development team as "main", "develop" or "head" and is analyzed when no specific branch parameters are provided. SonarQube labels this branch as Main Branch, and, with Community Edition, this is the only branch you can analyze.

Adding projects by DevOps Platform copies the main branch name in SonarQube from the main branch name in your repository. See DevOps Platform Integrations in the documentation navigation for more information on adding your project from a DevOps Platform.

If you add your project manually, your main branch defaults to the name main.

Renaming the main branch

Starting in Developer Edition: your main branch can be renamed from the project settings at Project Settings > Branches and Pull Requests. This is used mainly to maintain branch history when upgrading from Community Edition to a commercial edition (see section below).

Choosing a new main branch

Starting in Developer Edition, you can choose a different, existing branch to become the new main branch of a project. To do this:

1. Go to Project Settings > Branches & Pull Requests.
2. On the list of branches, click on the Actions cog button for the branch you want to make your main branch and click Set as main branch. 

Changing the main branch of your project will trigger project reindexing and may impact the level of information that is available for your project until reindexing is complete.

Impacts of choosing a new main branch

Choosing a new main branch has an effect on:

• New code: When some of a project’s branches use the main branch as a reference branch, changing the main branch does not update the new code settings. All branches continue to point to the previous main branch. If you want your reference branch to point to the new main branch, you must update the new code settings manually.
• Applications: The main branch of an application always references the main branch of a project, and changing the main branch of the project changes the main branch of the application. When a project’s main branch changes, the application is automatically scheduled for recomputation (see Managing applications > Calculation). After you change the main branch of a project, it can take a few minutes to propagate to the application.
• Portfolios: Portfolios are different from applications, as they can either reference the main branch of a project or a project’s branch specifically. 
  • In the first case, if you change the project's main branch, the portfolio starts referencing the new main branch of the project. The recomputation mechanics are the same as for applications.
  • In the second case, changing the project’s main branch does not change the portfolio, as the portfolio is referencing a specific branch.
• Branch analysis: 
  • Impacts on CI setup: Starting in Developer Edition, it is possible to analyze a branch without passing an explicit branch name (sonar.branch.name). In this case, the analysis automatically points to the main branch of the project. If you change the main branch, you could unintentionally have analyses from the old main branch go to the new branch. To avoid this, ensure the branch analysis is always pointing to a specific branch. 
  • Impacts on analysis processing:  If you change the main branch during a busy load of background tasks, it may impact certain background tasks that process analysis reports. This could lead to an inconsistent state. The solution is to re-analyze the project. This will put everything back into a consistent state.

Settings and quality profiles on branches

Branch settings and quality profiles are the same as those set for the main branch, and by design, it's not possible to configure other values. The new code definition is the only exception to this as it can be set on a branch-by-branch basis.

New code

You can set a new code definition for each branch. This is especially helpful if you are likely to develop and release multiple versions from the branch. See the Defining new code documentation for more information, and look at the Clean as You Code strategy to learn how to implement this best practice.

Quality gate

The branch quality gate lets you know if your branch is ready to be merged. Each branch has a quality gate that:

• Applies to conditions on new code and overall code.
• Assigns a status (passed or failed).

Setting up branch analysis

A branch is created when the sonar.branch.name parameter is passed during analysis.

Limiting analysis to relevant branches

You need to add a condition to your pipeline script to ensure that only the relevant branches are analyzed. For example, you wouldn't want to run analysis on feature branches that won't need analysis until they have pull requests.

In the following example, analysis would be limited to branches named main or release/*.

if [[ "$CI_BRANCH_NAME" == main ]] || [[ "$CI_BRANCH_NAME" == release/* ]]; then
  ./gradlew sonarqube
fi

Issue Creation and Synchronization

During the first analysis, issues (type, severity, status, assignee, change log, comments) are synchronized with the main branch. In each synchronized issue, a comment is added to the change log of the issue on the branch:  The issue has been copied from branch 'main' to branch '<branch>'.

At each subsequent analysis of the branch, any new issue in the main branch that comes from a pull request automatically inherits its attributes (type, severity, etc.) from the pull request. A comment is added to the change log of the issue on the branch: The issue has been merged from '<branch-1>' into '<branch-2>'

Issues can be synchronized between branches if you're using the Reference Branch new code definition. When using this new code definition, any new issue in the reference branch that comes from a feature branch automatically inherits its attributes (type, severity, etc.) from the feature branch. A comment is added to the change log of the issue on the branch: The issue has been merged from '<branch-1>' into '<branch-2>.

Fetching full Git history

By default, some CIs don't fetch your full Git history. For example, TravisCI only fetches the last 50 git commits. You must use git fetch --unshallow to get the full history. If you don't, new issues may not be assigned to the correct developer.

Managing inactive branches

Projects and branches that are not scanned for more than seven consecutive days are considered inactive, and SonarQube automatically deletes their cached data to free space in the database. 

If a project has several branches, only the cache of its inactive branches is deleted after seven days.

You can use housekeeping to automatically delete branches that are inactive (i.e. old feature branches) or to keep inactive branches that you want to continue maintaining (i.e. release branches).

Deleting inactive branches

You can set the number of days a branch can be inactive before it's deleted in the global settings at Administration > General Settings > Housekeeping > Number of days before deleting inactive branches. Branches that are inactive for the number of days that you set will be automatically deleted.

Using patterns to keep inactive branches

You can use naming patterns to protect specific branches, such as release branches, from automatic deletion. To do this, add a pattern using Java regular expressions under Administration > General Settings > Housekeeping > Branches > Branches to keep when inactive at either the global or project level. When a branch is created with a name that follows one of these patterns, it will be kept indefinitely.

For example, adding the pattern release/.* would keep any branches named release/6.0, release/7, and so on.

Note: Patterns aren't retroactive and won't apply to branches that have already been created. They only apply to branches created after the pattern is set. You can protect an existing branch at the project level. See the following section.

Managing inactive branches at a project level

You can set a branch to Keep when inactive at the project level from the Branches tab at Project Settings > Branches and Pull Requests. Here, you can also turn off protection for a branch so it will be deleted when it's inactive for the number of days that have been specified in the global settings at Administration > General Settings > Housekeeping > Number of days before deleting inactive branches.

Note: The main branch is always protected from automatic deletion, even if it's inactive. This can't be changed.

Keeping your main branch history when upgrading from Community Edition to a commercial edition

When upgrading to a current commercial edition version, automatic branch and pull request configuration creates branches based on their names in your code repository. If the name of your main branch in SonarQube doesn't match the branch's name in your code repository, the history of your main branch won't be taken on by the branch you analyze.

Before running analysis, you can keep your branch history by renaming the main branch in SonarQube with the name of the branch in your code repository at Project Settings > Branches and Pull Requests.

For example, if your main branch is named main in SonarQube but develop in your code repository, rename your main branch to develop in SonarQube.