# 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 web hooks.

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[1] on the Bitbucket server.
    • Password/Access Token: The user's password or personal access token with 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 web hook 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


If there are restrictions, so that Teamscale cannot receive Bitbucket web hooks or web hooks cannot be automatically created, please apply these advanced configuration options.

1: Administrative rights are needed for automatic creation of web hooks and to delete merge request comments created by Teamscale which a user has already replied to. In case administrative rights cannot be granted, please disable deletion of merge request comments with replies using the following JVM argument: -Dcom.teamscale.mergerequest.bitbucket.server.disable-comment-with-reply-deletion=true