Bitbucket Server

Project owners, as well as account owners and admins, can create a Bitbucket Server integration so that commits, pull requests and branches in Bitbucket Server automatically attach to the appropriate stories.

Creating a new Bitbucket Server integration

If you are a project owner, or an admin or owner of the account that includes the project, you can create a Bitbucket Server integration for the project. Check the integration permissions for more information.

Adding a new Bitbucket Server integration to a project

Click the INTEGRATIONS tab in your project view.
Select the Add an integration button at the top, then choose Bitbucket Server.

Configuring the integration

Next, you’ll need to configure the integration to work for one or more projects in your account.

Naming your integration: It’s important to name the integration so that it can be easily identified in the event it needs to be edited later. For example, “Frontend Bitbucket Server integration”, etc.
Pivotal Tracker Projects: You’ll need to pick which Tracker projects the Bitbucket Server integration can access. It is not necessary to set up individual Bitbucket Server integrations for each individual project on your account.
Base URL from Bitbucket Server: Enter the base URL for your Bitbucket server here.
Webhook Payload URL: You will need to paste this into the webhook configuration in Bitbucket.
Secret Token: The “secret token” is made available to you once the integration has been saved, and is the second piece of information you will need to setup webhooks in Bitbucket.

Creating the webhook on Bitbucket Server

Navigate to the webhook creation portion of a repository or organization as seen below. You can also visit the setup form directly at a link like:

[bitbucket server instance base url]/plugins/servlet/webhooks/projects/[project key]/repos/[repo name]/create

Fill in the form using settings as shown here:

Name Enter a name that will help you remember what this webhook is for
URL Enter the payload URL from the Tracker Bitbucket integration configuration page
Secret Enter the secret token from the Tracker Bitbucket integration configuration page
Events: For events, we recommend selecting the items shown

Using the Bitbucket Server integration: Branches

Attaching branches to a story automatically

If you create a branch from the command line and include the story id in the branch name, Tracker will automatically attach a branch to the story. For example, creating a branch with the name 123123-super-cool-feature will attach it to the story with id 123123.

Using the Bitbucket Server integration: Pull requests

Tracker will automatically attach a pull request to a story if the name of the branch that is being merged starts with that story’s ID, as described in Attaching Branches to a Story Automatically above. The PR icon’s color will match its status in Bitbucket.

= Merged

= Declined

= Created / Open

Attaching Bitbucket Server resources to your story

You can manually attach Bitbucket Server resources to your stories using the CODE field. Simply paste in the Bitbucket Server link to your pull request or branch, and it will be interpreted and attached.

Managing Bitbucket Server integrations

An existing Bitbucket Server integration can only be updated by the project owner, account owner, or admin who created the integration. Account owners and admins can delete any Bitbucket Server integrations for projects in their account. Check the integration permissions for more information.

Troubleshooting Tips

We’re sorry if you’re experiencing issues with your Bitbucket Server integration, and hope the following tips and troubleshooting steps might help.

Please make sure you’ve set up an integration for Bitbucket Server under INTEGRATIONS (as described in the Creating a new Bitbucket Server integration section above).
The creator of the integration should make sure they’ve added all of the Projects and Repositories they expect to push and receive from in the Bitbucket Server integration Configuration page (INTEGRATIONS).

If all of the above looks good, please consider the following:

It is not necessary to set up individual Bitbucket Server integrations for each individual project on your account. Any number of projects can be associated with any number of Bitbucket Server repositories and/or organizations in a single Bitbucket Server integration, regardless of which project you chose to start setting it up from.
Only project owners, as well as account owners/admins, can create new Bitbucket Server integrations.
Only the user who created a Bitbucket Server integration may edit that integration. Account owners and admins may view and delete integrations that they did not create, but they can’t edit them.

If the above does not help, please email support@pivotaltracker.com with answers to the following:

Is the issue to do with attaching PRs or branches?
The project(s) where the Bitbucket Server integration(s) has been configured (preferably the project IDs).
The project(s) that you are having the issue with.
The story ID for a story where the branch or PR did not appear.
The exact PR message or branch names that were used.
The approximate time (including Time Zone) of the action.

Learn more

The Tracker blog post announcing the Introducing new Bitbucket and Bitbucket Server Integrations has additional information.