Bitbucket Cloud integration

SonarQube Community Build'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 Community Build to easily set up SonarQube Community Build projects.
• Analyze projects with Bitbucket Pipelines: Integrate analysis into your build pipeline and fail your pipeline if the quality gate fails.
• Authenticate with Bitbucket Cloud: Sign in to SonarQube Community Build with your Bitbucket Cloud credentials.

Prerequisites

The SonarQube Server base URL must be properly set, otherwise, integration features will not work correctly. See Configuring the SonarQube Server base URL.

Importing your Bitbucket Cloud repositories into SonarQube Community Build

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.

To set up the import of BitBucket Cloud repositories:

1. Create an OAuth consumer.
2. Set your global DevOps Platform integration settings.
3. Add your Bitbucket username and an app password.

Creating your OAuth consumer

SonarQube Community Build uses a dedicated OAuth consumer to import repositories. 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 Community Build 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.

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:

• 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. Administrators can encrypt this secret: see Encrypting sensitive settings 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 Community Build. 

Analyzing projects with Bitbucket Pipelines

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 Community Build token for Bitbucket Cloud and create a custom, secure 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 Community Build URL as the Value.

Configuring your bitbucket-pipelines.yml file

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

The SonarQube Community Build doesn't support multiple branches, so you should only analyze your main branch. You can restrict the analysis to your main branch by setting it as the only branch in your branches pipeline; do this in your bitbucket-pipelines.yml file and not using the pull-requests pipeline.

Note: This assumes a typical gitflow workflow. See Use glob patterns on the Pipelines YAML file provided by Atlassian for more information.

image: <image for build>

definitions:
  steps: &build-step
    - step:
        name: SonarQube analysis
        image: sonarsource/sonar-scanner-cli:latest
        caches:
          - sonar
        script:
          - sonar-scanner
  caches:
    sonar: /opt/sonar-scanner/.sonar

clone:
  depth: full

pipelines:
  branches:
    '{master,main,develop}':
      - step: *build-step

  pull-requests:
    '**':
      - step: *build-step

Failing the pipeline job when the quality gate fails

You can use the SonarQube Community Build quality gate check Bitbucket Pipe to ensure your code meets your quality standards by failing your pipeline job when your quality gate fails.

If you do not want to use the SonarQube Community Build quality gate Check Pipe, you can instruct the scanner to wait for the SonarQube Community Build quality gate status at the end of the analysis. To enable this, pass the -Dsonar.qualitygate.wait=true parameter to the scanner in the bitbucket-pipelines.yml file.

This will make the analysis step poll SonarQube Community Build 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).

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.

Authenticating with Bitbucket Cloud

See the article on Bitbucket Cloud authentication for details to change your OAuth settings.

Troubleshooting

Docker memory limit

If your Pipelines fail with the error Container ‘docker' exceeded memory limit, you'll need to increase the memory limit for the docker process in your bitbucket-pipelines.yml file: 

...
definitions:
  services:
    docker:
      memory: 2048

pipelines: 
...

API request limit exceeded

If your Bitbucket Cloud API calls fail with HTTP 429 code and "Rate limit for this resource has been exceeded" error, try to use a dedicated Bitbucket user for SonarQube Community Build integration.