Bitbucket Server integration

SonarQube's integration with Bitbucket Server 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 repositories: Import your Bitbucket Server repositories into SonarQube to easily set up SonarQube 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 so you know if it's safe to merge your changes.

Prerequisites

• Integration with Bitbucket Server requires at least Bitbucket Server version 5.15.
• You've set a SonarQube Server base URL in Administration > Configuration > General Settings > General.

Branch Analysis

Community Edition doesn't support the analysis of multiple branches, so you can only analyze your main branch. Starting in Developer Edition, you can analyze multiple branches and pull requests.

Importing your Bitbucket Server repositories into SonarQube

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

To set up the import of BitBucket Server 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 instances URL. For example, https://bitbucket-server.your-company.com.
• Personal Access Token: A Bitbucket Server user account is used to decorate Pull Requests. We recommend using a dedicated Bitbucket Server 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 the Settings Encryption section of the Security page 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 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 and can be revoked at any time in Bitbucket Server.

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

Reporting your quality gate status to the Bitbucket server

After you've set up SonarQube to import your Bitbucket Server repositories as shown in the previous section, SonarQube can report your quality gate status and analysis metrics directly to your Bitbucket Server 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 to analyze your project. SonarQube automatically sets the project settings required to show your quality gate in your pull requests.

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 can also report your quality gate status to Bitbucket Server 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 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 repository URL (.../projects/<key>/repos/<slug>/browse).

Advanced configuration

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, 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.