Bitbucket Cloud integration
SonarQube's integration with Bitbucket Cloud allows you to maintain code quality and security in your Bitbucket Cloud repositories.
With this integration, you'll be able to:
- Import your BitBucket Cloud repositories: Import your Bitbucket Cloud repositories into SonarQube to easily set up SonarQube projects.
- Analyze projects with Bitbucket Pipelines: Integrate analysis into your build pipeline. SonarScanners running in Bitbucket Pipelines can automatically detect branches or pull requests being built so you don't need to specifically pass them as parameters to the scanner (branch and pull request analysis is available starting in Developer Edition).
- Report your quality gate status to your pull requests (starting in Developer Edition): See your quality gate and code metric results right in Bitbucket Cloud so you know if it's safe to merge your changes.
- Authenticate with Bitbucket Cloud: Sign in to SonarQube with your Bitbucket Cloud credentials.
Importing your Bitbucket Cloud repositories into SonarQube
Setting up the import of BitBucket Cloud repositories into SonarQube allows you to easily create SonarQube projects from your Bitbucket Cloud repositories. This is also the first step in adding authentication and, starting in Developer Edition, the first step in reporting your analysis and quality gate status to your pull requests.
To import your Bitbucket repositories into SonarQube, you can only have one global configuration of Bitbucket, including Bitbucket Server and Bitbucket Cloud. See the Configuring multiple DevOps platform instances section below for more information.
To set up the import of BitBucket Cloud repositories:
- Create an OAuth consumer.
- Set your global DevOps Platform integration settings.
- Add your Bitbucket username and an app password.
Creating your OAuth consumer
SonarQube uses a dedicated OAuth consumer to import repositories and display your quality gate status on pull requests. Create the OAuth consumer in your Bitbucket Cloud workspace settings and specify the following:
- Name: The name of your OAuth consumer
- Callback URL: Bitbucket Cloud requires this field, but it's not used by SonarQube so you can use any URL.
- This is a private consumer: Your OAuth consumer needs to be private. Make sure this check box is selected.
- Permissions: Grant Read access for the Pull requests permission.
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 Cloud 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 Cloud configuration at the project level. Use something succinct and easily recognizable.
- Workspace ID: The workspace ID is part of your bitbucket cloud URL
- OAuth Key: Bitbucket automatically creates an OAuth key when you create your OAuth consumer. You can find it in your Bitbucket Cloud workspace settings under OAuth consumers.
- OAuth Secret: Bitbucket automatically creates an OAuth secret when you create your OAuth consumer. You can find it in your Bitbucket Cloud workspace settings under OAuth consumers. Administrators can encrypt this secret at Administration > Configuration > Encryption. See the Settings Encryption section of the Security page for more information.
Adding your Bitbucket username and an app password
After setting your global settings, you can add a project from Bitbucket Cloud 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 your Bitbucket username and an app password. Your app password needs the repository:read permission.
After adding your Bitbucket username and app password, you'll see a list of your Bitbucket Cloud projects that you can set up by adding them to SonarQube. Setting up your projects this way also sets your project settings to display your quality gate status on pull requests.
Analyzing projects with Bitbucket Pipelines
SonarScanners running in Bitbucket Pipelines can automatically detect branches or pull requests being built so you don't need to specifically pass them as parameters to the scanner.
To analyze your projects with Bitbucket Pipelines, you need to:
- Set your environment variables.
- Configure your
Setting environment variables
You can set environment variables securely for all pipelines in Bitbucket Cloud's settings. See User-defined variables for more information.
You may need to commit your
bitbucket-pipelines.yml before being able to set environment variables for pipelines.
You need to set the following environment variables in Bitbucket Cloud for analysis:
SONAR_TOKEN: Generate a SonarQube token for Bitbucket Cloud and create a custom secured environment variable in Bitbucket Cloud with
SONAR_TOKENas the Name and the token you generated as the Value.
SONAR_HOST_URL: Create a custom environment variable with
SONAR_HOST_URLas the Name and your SonarQube server URL as the Value.
Configuring your bitbucket-pipelines.yml file
This section shows you how to configure your
You'll set up your build according to your SonarQube edition:
- Community Edition: Community Edition doesn't support multiple branches, so you should only analyze your main branch. You can restrict analysis to your main branch by setting it as the only branch in your
branchespipeline in your
bitbucket-pipelines.ymlfile and not using the
- Developer Edition and above: Bitbucket Pipelines can build specific branches and pull requests if you use the
pull-requestspipelines as shown in the example configurations below.
Click the scanner you're using below to expand the example configuration:
Note: This assumes a typical gitflow workflow. See Use glob patterns on the Pipelines YAML file provided by Atlassian for more information on customizing which branches or pull requests trigger an analysis.
Failing the pipeline job when the quality gate fails
If you do not want to use the SonarQube quality gate Check Pipe, you can instruct the scanner to wait for the SonarQube quality gate status at the end of the analysis. To enable this, pass the
-Dsonar.qualitygate.wait=true parameter to the scanner in the
This will make the analysis step poll SonarQube regularly until the quality gate is computed. This will increase your pipeline duration. Note that, if the quality gate is red, this will make the analysis step fail, even if the actual analysis itself is successful. We advise only using this parameter when necessary (for example, to block a deployment pipeline if the quality gate is red). It should not be used to report the quality gate status in a pull request.
You can set the
sonar.qualitygate.timeout property to an amount of time (in seconds) that the scanner should wait for a report to be processed. The default is 300 seconds.
For more information
For more information on configuring your build with Bitbucket Pipelines, see the Configure bitbucket-pipelines.yml documentation provided by Atlassian.
Reporting your quality gate status in Bitbucket Cloud
After creating and installing your OAuth consumer above, SonarQube can report your quality gate status and analysis metrics directly to your Bitbucket Cloud pull requests.
To do this, add a project from Bitbucket by clicking 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.
To report your quality gate status in your pull requests, a SonarQube 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.
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 Cloud pull requests for existing and manually-created projects. After you've created and installed your OAuth consumer and updated your global settings as shown in the Importing your Bitbucket Cloud 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 GitHub instance.
- Repository SLUG: The Repository SLUG is part of your Bitbucket Cloud URL. For example,
Authenticating with Bitbucket Cloud
See the article on Bitbucket Cloud authentication for details to change your OAuth settings.
Preventing pull request merges when the quality gate fails
After setting up a pull request analysis, you can block pull requests from being merged if it is failing the quality gate. There are two options to accomplish this (both methods require a Premium Bitbucket Cloud plan).
Option 1: if using Bitbucket Pipelines
- You must be using Bitbucket Pipelines with a Premium Bitbucket Cloud plan.
- Make sure that the Bitbucket Pipeline fails when quality gate fails (refer to Failing the pipeline job when the quality gate fails above)
- In Bitbucket, go to Repository settings > Branch restrictions to either Add a branch restriction or edit your existing one:
- In the Merge settings tab, select:
- Minimum number of successful builds for the last commit with no failed builds and no in progress builds and
- Prevent a merge with unresolved merge checks
- In the Merge settings tab, select:
Option 2: counting your builds
If you know how many builds you have for a PR, you can run your SonarQube analysis and not block the pipeline waiting for results. The SonarQube Quality Gate will appear in the build for your PR after the analysis results are available.
You can set the Minimum number of successful builds for the last commit with no failed builds and no in progress in Bitbucket, to the number of builds that run for the PR.
Preventing pull request merges when the quality gate fails is not supported for mono repositories.
© 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.