How to Connect Teamscale to Bitbucket

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

General Option Reference

This guide only covers the options specific for the Bitbucket Cloud/Server repository connector. A general overview of connector options is available here.

• Bitbucket Cloud Integration
• Bitbucket Server (On-Premise) Integration
  • Required Permissions
  • Manual Creation of Webhooks

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 workspace used to register the Bitbucket App. Please note that this app needs to be installed on the workspace, so that Teamscale has access to all available repositories of your workspace.

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 workspace. Open Installed apps and click the link Install app from URL. You might also need to enable the development mode on the bottom of the page. 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.

Set the repository name option in the connector to projectKey/repoSlug.

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 7.0.0.

To connect a project to code from a Bitbucket project, you don't need to install plugins in Bitbucket or change admin settings. 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.

Required Permissions

It is required that the technical user has REPO_ADMIN permissions. 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 setting the corresponding expert option of the repository connector. You can also set the default of this option for new projects by passing the following JVM argument on the start of Teamscale: -Dcom.teamscale.mergerequest.disable-automatic-webhook-creation-default=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.

Even if the technical user may not be granted administrative rights or if they are taken away after the initial webhook setup, the user still requires write permissions. These permissions enable Teamscale to edit pull-request descriptions. If the user lacks these permissions, Teamscale may not enhance pull requests with finding information.

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, Source branch updated, Modified, Merged, Declined, Deleted
5. Click Create.

TIP

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