Integrating CodeScene with Bitbucket Pull Requests

You can integrate CodeScene with Bitbucket to run delta analyses automatically on pull requests. This provides automated feedback through quality gates, ensuring that code health and quality standards are enforced early in the development process.

1. Prerequisites

Before enabling the integration:

Configure the CodeScene host URL under
Global Configuration → System → Host/Network Settings.
Ensure your CodeScene instance is accessible from Bitbucket.
(Bitbucket needs to send webhooks to CodeScene.)
If you are running CodeScene locally (trial setup), see the Important Note at the end of this article.

2. Enable Pull Request Integration

Go to the Projects page in CodeScene and locate your project.
Open Project Configuration → PR Integration.
Enable the Pull Request Integration and select Bitbucket as the integration type.

3. Specify a Bitbucket API Token with Scopes

App passwords have been replaced by API tokens. As of September 9, 2025, app passwords can no longer be created. Use API tokens with scopes instead. All existing app passwords will be disabled on June 9, 2026. Migrate any integrations before then to avoid disruptions.

Follow these steps to create an API token with scopes:

In Bitbucket, click on Settings (⚙️).
Navigate to:
Atlassian account settings → Security → API tokens section
or visit directly: https://id.atlassian.com/manage-profile/security/api-tokens
Click Create and manage API tokens.
Click Create API token with scopes.
Enter a descriptive name, for example:
```
CodeScene Integration 
```
Under Expires on, choose an appropriate expiration date.
⚠️ Note: Tokens can last no longer than 365 days.
Click Next.
Under the Select API token app, choose:
```
Bitbucket 
```
Click Next and then select the following scopes:
- read:pullrequest:bitbucket
- write:pullrequest:bitbucket
- read:webhook:bitbucket
- write:webhook:bitbucket
Click Next again to review your details, then click Create token.
Copy your API token and store it safely - preferably in a password manager, since you won’t be able to view it again later.

4. Configure Bitbucket Credentials in CodeScene

In the Pull Request Integration tab, choose one of the following setup methods:

Option A: Use a Bitbucket Connection Preset (Recommended)

Select a Connection Settings Preset if you’ve already created one for Bitbucket.
Learn more about connection presets here.
Click Save Configuration.

Option B: Configure Credentials Manually

Under the Bitbucket Credentials section, provide:
- Bitbucket Username
- Bitbucket Api Token
  The API token must include the following permissions:
  - read:pullrequest:bitbucket
  - write:pullrequest:bitbucket
  - read:webhook:bitbucket
  - write:webhook:bitbucket
Toggle Advanced Settings and verify:
- Bitbucket API URL – Leave blank to use the default API URL based on your repository path.
- CodeScene Host URL – Used by external webhooks to reach your CodeScene instance. Leave blank to use the global host URL.
Click Save Configuration.

5. Optional: Configure PR Feedback Options

CodeScene can provide several types of automated feedback on your Bitbucket pull requests:

Add a Build Status

Posts a build status on your PRs.
Can be made a requirement for merging, acting as a quality gate.

Add a Code Insights Report

Posts a Code Insights report to Bitbucket.
A negative report will not block merges, but it highlights issues for the reviewer.

Add Annotations to Code Insights Report

If Code Insights are enabled, CodeScene can add annotations directly on lines of code where degradations or improvements occurred.

6. Customize PR Feedback

Automated Code Health Review

You can customize what CodeScene checks in each PR by configuring your Code Quality Profile:

In your project, navigate to
Configuration → Delta Analysis.
Select a Code Quality Profile that fits your project’s needs. We recommend starting with the Bare Minimum profile.
Learn more about quality profiles here.

7. Test the Configuration

Create a Pull Request in Bitbucket.
Verify that CodeScene:
- Posts a review comment in the PR discussion thread.
- Displays build status and/or Code Insights reports (depending on configuration).

Important Note for On-Premises Trials

When running CodeScene locally (e.g., using a trial Docker setup):

Bitbucket webhooks require inbound communication from Bitbucket’s servers to your CodeScene instance.
If your CodeScene instance is not publicly accessible, Bitbucket cannot deliver webhook events.

Workaround

Use a tunneling service such as ngrok to expose your local CodeScene instance to the internet.

ngrok creates a temporary, secure tunnel between Bitbucket and CodeScene.
This allows webhooks to work without changing your firewall or public IP configuration.