Branch analysis is available starting in Developer Edition.
With branch analysis, you can ensure that you're maintaining consistent code quality all the way down to the branch level of your projects.
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", "master" 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 an DevOps Platform.
If you add your project manually, your main branch defaults to the name
Starting in Developer Edition, your main branch can be renamed from the project settings at Project Settings > Branches and Pull Requests.
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.
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.
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.
Scanners can automatically detect branch parameters when running on the following CI services:
- Azure Pipelines
- Bitbucket Pipelines
- Cirrus CI
- GitHub Actions
- GitLab CI/CD
- Jenkins (with the Branch Source plugin configured)
Manually setting branch parameters overrides automatic detection.
|Name of the branch (visible in the UI)|
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, the analysis would be limited to branches named
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
Inactive branches are branches that are no longer being analyzed. 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/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 "master" branch history when upgrading from Community Edition to a commercial edition
If you added a SonarQube project from a DevOps platform instead of manually, the name of the main branch in SonarQube is copied from the name of the main branch in your repository, and you shouldn't have any branch history issues when upgrading to a commercial edition.
In Community Edition, if you create a project manually, your analyzed branch is named
master by default.
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
master in SonarQube but
develop in your code repository, rename your main branch
develop in SonarQube.
© 2008-2022, SonarSource S.A, Switzerland. Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution-NonCommercial 3.0 United States License. SONARQUBE is a trademark of SonarSource SA. All other trademarks and copyrights are the property of their respective owners.