On this page

Analyzing projects with Bitbucket PipelinesAdding pull request decoration to Bitbucket Cloud

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:

  • 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).
  • Add pull request decoration - (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.

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 bitbucket-pipelines.yml file.

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 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_TOKEN as the Name and the token you generated as the Value.
  • SONAR_HOST_URL: Create a custom environment variable with SONAR_HOST_URL as the Name and your SonarQube server URL as the Value.

Configuring your bitbucket-pipelines.yml file

This section shows you how to configure your bitbucket-pipelines.yml file.

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 branches pipeline in your bitbucket-pipelines.yml file and not using the pull-requests pipeline.
  • Developer Edition and above: Bitbucket Pipelines can build specific branches and pull requests if you use the branches and pull-requests pipelines 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 whi branches or pull requests trigger an analysis.

Failing the pipeline job when the quality gate fails

In order for the Quality Gate to fail the pipeline when it is red on the SonarQube side, the scanner needs to wait for the SonarQube Quality Gate status. To enable this, pass the -Dsonar.qualitygate.wait=true parameter to the scanner in the bitbucket-pipelines.yml file.


mvn verify sonar:sonar -Dsonar.qualitygate.wait=true

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, as this is already done with pull request decoration.

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.

Adding pull request decoration to Bitbucket Cloud

Pull request decoration shows your Quality Gate and analysis metrics directly in Bitbucket Cloud. To set up pull request decoration, you need to do the following:

  1. Set up a dedicated OAuth consumer to decorate your pull requests.
  2. Set your global ALM Integration settings.
  3. Set your project-level Pull Request Decoration settings.

Setting up your OAuth consumer

SonarQube uses a dedicated OAuth consumer to decorate pull requests. You need to 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 ALM Integration settings

To set your global ALM Integration settings, navigate to Administration > ALM 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 GitHub configuration at the project level. Use something succinct and easily recognizable.
  • Workspace ID: The workspace ID is part of your bitbucket cloud URL https://bitbucket.org/{WORKSPACE-ID}/{repository-slug}.
  • 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.

Setting your project-level Pull Request Decoration settings

From your project Overview, navigate to Project Settings > General Settings > Pull Request Decoration.

From here, set your:

  • Configuration name: The configuration name that corresponds to your Bitbucket Cloud instance.
  • Repository SLUG: The repository SLUG is part of your bitbucket cloud URL https://bitbucket.org/{workspace-id}/{REPOSITORY-SLUG}.

© 2008-2023, 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.

Creative Commons License