# How to Connect Teamscale to Bitbucket

Teamscale can connect to both the Bitbucket Cloud version, as well as the Bitbucket Server (On-Premise) version.

Screenshot of the Bitbucket Plugin's Findings Badge

# Bitbucket Cloud Integration

Teamscale integrates with Bitbucket Cloud as a Bitbucket App. Please note that this is currently a beta feature. Prerequisites for the configuration are:

  • Teamscale license with Bitbucket support enabled.
  • Teamscale installation that can be reached from the Bitbucket Cloud instance you want to connect to.
  • Bitbucket team used to register the Bitbucket App. Please note that this app needs to be installed on the team account, so that Teamscale has access to all available repositories of your team.
  • Bitbucket team account's username and nickname must match.

To connect to Bitbucket cloud, the following steps are needed:

  1. Ensure that the Teamscale instance base URL is configured correctly.

  2. In Bitbucket, navigate to the settings page of your team. Open Installed apps and click the link Install app from URL. Here you can provide the App URL to directly install the app.

    • App URL: This is the public URL of your Teamscale installation followed by _api/bitbucket-cloud/app/install_. So for the sample Teamscale URL https://teamscale.acme.com, this would be https://teamscale.acme.com/api/bitbucket-cloud/app/install.
  3. After clicking Install, the app will request access to Bitbucket. Click Grant access. You will get a message that the app has been successfully installed and will appear in the list of installed apps.

No Automatic Project Mirroring

Note that Teamscale projects are not automatically created, but rather have to be created as needed using the Bitbucket connector after the app has been installed.

When testing Teamscale on a local laptop or during initial setup, a service for exposing local ports on the internet can be helpful. One such service is ngrok.

# Bitbucket Server (On-Premise) Integration

Teamscale integrates with Bitbucket Server (On-Premise) using the available API and webhooks.

Minimum Bitbucket Version

The minimum required Bitbucket server version for the integration to work is 5.10.0.

To connect a project to code from a Bitbucket project, no global configuration is required. You just need to follow these steps:

  1. Ensure that the Teamscale instance base URL is configured correctly.

  2. Select the Bitbucket Server (On-Premise) connector during project creation.

  3. Select or create an account for the Bitbucket server. The account's fields should be filled out as follows:

    • URI: Bitbucket server's root URL (e.g., https://bitbucket.example.com).
    • Username: The username of a user who has REPO_ADMIN rights on the Bitbucket server.
    • Password/Access Token: The user's password or personal access token with REPO_ADMIN permissions for both the project and repository. To obtain a personal access token in Bitbucket, navigate to your user's Manage account page and select the Personal access tokens page.
  4. Complete project creation as usual, by providing the full name of the Bitbucket repository and completing any other required fields. The name should be in this format projectKey/repoSlug.

As the first step in project creation, Teamscale will register its webhook with the project. After this, Teamscale will automatically be informed about events in the project, such as pushes to the repository and changes to any pull requests.

Screenshot of the Bitbucket Plugin's Line Comments

# Required Permissions

It is required that the technical user should have REPO_ADMIN rights. These permissions are needed in order for Teamscale to:

  • Automatically create the necessary webhooks in the Bitbucket repository.
  • Delete pull request comments created by Teamscale to which a user has already replied.

In case administrative rights cannot be granted to the technical user, please do the following:

  1. Disable automatic webhook creation by passing the following JVM argument on the start of Teamscale: -Dcom.teamscale.mergerequest.disable-automatic-webhook-creation=true
  2. Disable deletion of merge request comments with replies using the following JVM argument: -Dcom.teamscale.mergerequest.bitbucket.server.disable-comment-with-reply-deletion=true
  3. Manually create the necessary webhooks in Bitbucket.

# Manual Creation of Webhooks

In case the technical user does not have administrative rights, you will need to manually create and configure webhooks in the Bitbucket repository.

  1. Open the Bitbucket repository you want to add the webhook to.
  2. From Repository settings, click Webhooks.
  3. Click the Create webhook button.
  4. Configure the webhook as follows:
    • Name: Enter any name for the webhook (e.g. "Teamscale Webhook").
    • URL: Enter the URL of Teamscale's Bitbucket endpoint. It should be in the following format: {Teamscale_baseURL}/api/bitbucket-server/web-hook
    • Events: Select the following events:
      • Repository: Push
      • Pull request: Opened, Modified, Merged, Declined, Deleted
  5. Click Create.


If there are restrictions, so that Teamscale cannot receive Bitbucket webhooks, please apply these advanced configuration options.