Bitbucket Server & Data Center

SonarQube Server’s integration with Bitbucket Server and Data Center allows you to maintain code quality and security in your Bitbucket Server repositories.

With this integration, you’ll be able to:

• Import your BitBucket Server or Data Center repositories: Import your Bitbucket Server or Data Center repositories into SonarQube Server to easily set up SonarQube Server projects.

• Report your Quality Gate status to your pull requests (starting in Developer Edition): See your Quality Gate and code metric results right in Bitbucket Server or Data Center so you know if it’s safe to merge your changes.

Prerequisites

You’ve set a SonarQube Server base URL in SonarQube Server: see Server base URL.

Branch Analysis

You can analyze multiple branches and pull requests.

Importing your Bitbucket Server repositories into SonarQube Server

Setting up the import of BitBucket Server or Data Center repositories into SonarQube Server allows you to easily create SonarQube Server projects from your Bitbucket Server or Data Center repositories. If you’re using Developer Edition or above, this is also the first step in adding pull request decoration.

To import your Bitbucket repositories into SonarQube Server, you can only have one global configuration of Bitbucket, including Bitbucket Server, Data Center, and Cloud. See the Configuring multiple DevOps platform instances section below for more information.

To set up the import of BitBucket Server or Data Center repositories:

1. Set your global DevOps Platform integration settings

2. Add a personal access token for importing repositories

Setting your global DevOps platform integration settings

To set your global DevOps Platform Integration settings, navigate to Administration > Configuration > General Settings > DevOps Platform Integrations, select the Bitbucket tab, and select Bitbucket Server as the variant you want to configure. From here, specify the following settings:

• Configuration Name (Enterprise and Data Center Edition only): The name used to identify your Bitbucket Server configuration at the project level. Use something succinct and easily recognizable.

• Bitbucket Server URL: your Server or Data Center instance URL. For example, https://bitbucket-server.your-company.com.

• Personal Access Token: A Bitbucket Server or Data Center user account is used to decorate Pull Requests. We recommend using a dedicated Bitbucket Server / Data Center account with Administrator permissions. You need a Personal Access Token from this account with Read permission for the repositories that will be analyzed. Administrators can encrypt this token at Administration > Configuration > Encryption. See Sensitive settings for more information. This personal access token is used to report your Quality Gate status to your pull requests. You’ll be asked for another personal access token for importing projects in the following section.

Adding a personal access token for importing repositories

After setting your global settings, you can add a project from Bitbucket Server or Data Center by clicking the Add project button in the upper-right corner of the Projects homepage and selecting Bitbucket.

Then, you’ll be asked to provide a personal access token from your user account with Read permissions for both projects and repositories. This token will be stored in SonarQube Server and can be revoked at any time in Bitbucket Server or Data Center.

After saving your personal access token, you’ll see a list of your Bitbucket Server or Data Center projects that you can set up and add to SonarQube Server. Setting up your projects this way also sets your project settings for pull request decoration.

Reporting your quality gate status to Bitbucket Server or Data Center

After you’ve set up SonarQube Server to import your Bitbucket Server repositories as shown in the previous section, SonarQube Server can report your quality gate status and analysis metrics directly to your Bitbucket Server or Data Center pull requests.

To do this, add a project from Bitbucket by selecting the Add project button in the upper-right corner of the Projects homepage and select Bitbucket from the drop-down menu.

Then, follow the steps in SonarQube Server to analyze your project. SonarQube Server automatically sets the project settings required to show your quality gate in your pull requests.

To report your quality gate status in your pull requests, a SonarQube Server analysis needs to be run on your code. You can find the additional parameters required for pull request analysis on the pull request analysis page. See Setting up the pull request analysis for more information.

If you’re creating your projects manually or adding quality gate reporting to an existing project, see the following section.

Reporting your quality gate status in manually created or existing projects

SonarQube Server can also report your quality gate status to Bitbucket Server or Data Center for existing projects and manually-created projects. After you’ve updated your global settings as shown in the Importing your Bitbucket Server repositories into SonarQube Server section above, set the following project settings at Project Settings > General Settings > DevOps Platform Integration:

• Configuration name: The configuration name that corresponds to your DevOps Platform instance.

• Project Key: the project key is part of your BitBucket Server repository URL (.../projects/<key>/repos/<slug>/browse).

• Repository SLUG: The repository slug is part of your BitBucket Server / Data Center repository URL (.../projects/<key>/repos/<slug>/browse).

Advanced configuration

Reporting your quality gate status on pull requests in a monorepo

Reporting quality gate statuses to pull requests in a monorepo setup is supported starting in Enterprise Edition.

In a monorepo setup, multiple SonarQube Server projects, each corresponding to a separate project within the monorepo, are all bound to the same Bitbucket Server repository. You’ll need to set up each SonarQube Server project that’s part of a monorepo to report your quality gate status.

You need to set up projects that are part of a monorepo manually as shown in the Reporting your quality gate status in manually created or existing project section above. You also need to set the Enable monorepo support setting to true at Project Settings > General Settings > DevOps Platform Integration.

After setting your project settings, ensure the correct project is being analyzed by adjusting the analysis scope and pass your project names to the scanner. See the following sections for more information.

Ensuring the correct project is analyzed

You need to adjust the analysis scope to make sure SonarQube Server doesn’t analyze code from other projects in your monorepo. To do this, set up a Source file inclusion for your project at Project Settings > Analysis Scope with a pattern that will only include files from the appropriate folder. For example, adding ./MyFolderName/**/* to your inclusions would only include code in the MyFolderName folder for analysis. For more information, see Setting your project's analysis scope Setting the analysis scope of your project page.

Passing project names to the scanner

Because of the nature of a monorepo, SonarQube Server scanners might read all project names of your monorepo as identical. To avoid having multiple projects with the same name, you need to pass the sonar.projectName parameter to the scanner. For example, if you’re using the Maven scanner, you would pass mvn org.sonarsource.scanner.maven:sonar-maven-plugin:sonar -Dsonar.projectName=YourProjectName.

Configuring multiple DevOps platform instances

SonarQube Server can report your quality gate status to multiple DevOps platform instances. To do this, you need to create a configuration for each DevOps platform instance and assign that configuration to the appropriate projects.

• As part of Developer Edition, you can create one configuration for each DevOps platform.

• Starting in Enterprise Edition, you can create multiple configurations for each DevOps platform.

Linking issues

When adding a quality gate status to your pull requests, individual issues will be linked to their SonarQube Server counterparts automatically. For this to work correctly, you need to set the instance’s Server base URL (Administration > Configuration > General Settings > General > General) correctly. Otherwise, the links will default to localhost.

Preventing pull request merges when the quality gate fails

After setting up pull request analysis, you can block pull requests from being merged if it is failing the quality gate. To do this:

1. In Bitbucket Server or Data Center, navigate to Repository settings > Code Insights.

2. Add a Required report called com.sonarsource.sonarqube

3. Select Must pass as the Required status.

4. Select Must not have any annotations as the Annotation requirements.

Preventing pull request merges when the quality gate fails is not supported for monorepos.