Setting up the branch analysis

In SonarQube Server, branch analysis allows you to trigger an analysis on a push to any specified branch without involving pull requests.

To set up branch analysis:

1. Add the analysis step to your multi-branch CI pipeline. See the corresponding section of your CI tool in this documentation:

   • Adding analysis to a Jenkins job

   • Introduction

   • Bitbucket Cloud integration

   • Codemagic integration

   • Adding analysis to GitHub Actions workflow

   • Adding analysis to GitLab CI/CD pipeline

2. Make sure the branch to be analyzed is properly checked out in the CI repository: see Checked-out code.

3. Make sure that the SonarScanner gets the branch name parameter (otherwise the analysis will be performed on the main branch): see Setting up the branch name parameter below. If SonarQube's main branch doesn't match your repository's default branch, see Main branch alignment.

4. Limit the analysis to the relevant branches: see Limiting the analysis to the relevant branches below.

5. To configure your quality standard settings for the branches: see Configuring the settings for branches.

Setting up the branch name parameter

The SonarScanner can automatically detect the branch name parameters when running on the following CI services (you don’t need to perform any additional setup):

• Azure Pipelines

• Bitbucket Pipelines

• Cirrus CI

• Codemagic

• GitHub Actions

• GitLab CI/CD

• Jenkins (with the Branch Source plugin configured, see the Setting up Jenkins page)

The table below shows the branch name parameter. See Analysis parameters for information about the setup of analysis parameters for the scanner.

Parameter Name	Description
sonar.branch.name	Name of the branch (visible in the UI)

Main branch alignment

SonarQube keeps its own notion of the project's main branch. That branch can differ from the default branch in your SCM or CI (for example, your repository uses develop as the main branch while SonarQube uses main as the main branch). When they don't match, an analysis of your repository's default branch can update the wrong branch in SonarQube.

This often happens because:

• The CI's main branch name is available in the CI environment variables, but the SonarScanner does not set it explicitly as the main branch for SonarQube.

• SonarQube then defaults to using its current main branch to receive the analysis.

• The result is that you analyze your default branch in CI (in the example, develop) but SonarQube applies the results to a different branch (in the example, main).

If your CI's default branch doesn't yet exist in SonarQube, you cannot set it as the main branch in SonarQube until you first run an analysis on that branch. To align SonarQube's main branch with your repository's default branch:

1. Run an analysis with sonar.branch.name set explicitly to your CI's default branch name (in the example, sonar.branch.name=develop). That creates the develop branch in SonarQube.

2. In SonarQube, set that branch as the main branch for your project. See the article, Choosing a new main branch, for instructions.

3. After choosing your new main branch, you can omit sonar.branch.name for the default branch in CI; SonarQube will treat develop as the main branch.

Limiting the analysis to the 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

Configuring the settings for branches

See Quality standards and new code to learn how to implement this best practice.

The quality gate cannot be configured at the branch level, only at the project level. And ideally, all projects will use the same quality gate: see Understanding quality gates.

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 the Quality standards and new code page for more information.

When using any new code period type other than Reference branch, we recommend completing your merges using the fast-forward option without a merge commit; examples include GitHub’s squash and merge or rebase and merge options. In this way, the blame for the merged commits will always have a more recent commit date.