Bitbucket

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

Creating a new Bitbucket integration

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

Adding a new Bitbucket Integration to a project

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

Configuring the integration

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

Creating the webhook on Bitbucket

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:

https://bitbucket.org/[organization name]/[repo name]/admin/addon/admin/bitbucket-webhooks/bb-webhooks-repo-admin

Fill in the form using settings as shown here:

Using the Bitbucket 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 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

Using the Bitbucket integration: Commits

If your project has a Bitbucket integration and webhook setup, you can also attach commits to a story’s activity/comment stream by using a commit message tagged with the story id. The syntax for your commit message is pretty simple. Add the Tracker story id with a preceding hash symbol within square brackets at the end of your commit message. Optionally, you can include a state change for the Tracker story within the brackets. Currently, there are two state changes supported: Finished and Delivered. For example, including “Finishes” or “Fixes” in your commit message will change the specified story to the Finished state, while “Delivers” will change the specified story to Delivered state.

[(Finishes|Fixes|Delivers) #TRACKER_STORY_ID]

The commit message in the example below adds a commit to story 123123 and changes story state to “Finished” with the “finishes” keyword.

git commit -m "[finishes #123123] Updated settings for holograph projector"

If you just fixed a CSS bug for story #109683950, your commit might look like this:

You can specify multiple story ids in a commit by separating each id with a comma or space, within square brackets. However, all story ids will show in the commit on all specified stories.

[#TRACKER_STORY_ID,#TRACKER_STORY_ID] or [#TRACKER_STORY_ID #TRACKER_STORY_ID]

Alternatively, you can place each story id in its on set of square brackets, and separate each set of brackets with a comma or space. This will prevent story ids from showing up in non-related stories.

[#TRACKER_STORY_ID],[#TRACKER_STORY_ID] or [#TRACKER_STORY_ID] [#TRACKER_STORY_ID]

Attaching Bitbucket resources to your story

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

Managing Bitbucket integrations

An existing Bitbucket 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 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 integration, and hope the following tips and troubleshooting steps might help.

• Please make sure you’ve set up and authenticated an integration for Bitbucket under INTEGRATIONS (as described in the Creating a new Bitbucket 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 commits from in the Bitbucket Integration Configuration page (INTEGRATIONS).
• Within Bitbucket, please ensure that the Organization you want to connect to via an integration allows third-party access to Pivotal Tracker under Settings > Third-Party Access.

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

• It is not necessary to set up individual Bitbucket Integrations for each individual project on your account. Any number of projects can be associated with any number of Bitbucket repositories and/or organizations in a single Bitbucket 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 Integrations.
• Only the user who created a Bitbucket 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:

1. Is the issue to do with posting commit messages, attaching PRs or branches?
2. The project(s) where the Bitbucket Integration(s) has been configured (preferably the project IDs).
3. The project(s) that you are having the issue with.
4. The story ID for a story where the commit message comment, branch or PR did not appear.
5. The exact commit message, PR message or branch names that were used.
6. 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.