HacknPlan can be integrated with BitBucket to link your commits to the work items they are related to, allowing you to have a list of the changes on the code always at hand on the task detail panel. To be notified about the commits, a webhook needs to be configured pointing to our server, which will receive the data from push events and will analyze the commit messages looking for task IDs with the prefix hnp-, something like hnp-5 for task #5 (this prefix can be modified in the integration settings)

Note: GitLab integration is available for Personal Plus and Studio users only. Only integration with BitBucket Cloud is available at the moment. BitBucket Server will be released in further updates.

You can integrate a BitBucket repository from the Administration → Integrations section of your project. Click on the New button on the BitBucket panel, and a popup dialog will be launched. 

Before being able to select a repository, you need to provide the necessary credentials to connect to BitBucket Cloud: username and app password.

• Username: You can extract your username from your full repository name (username/repositoryname) or from your profile URL (https://bitbucket.org/username/). The email address won’t work as a username.
• App password: The app password is a special token associated with your account you can create to connect other applications to your BitBucket Cloud data.

Creating an app password

To create an app password for HacknPlan, go to your BitBucket profile settings and click on App passwords link under the Access Management category. Then click on the Create app password button. You need to set up the label and the permissions as you can see in the following picture:

Here you are giving us access to read your account basic info (name, email, etc), the teams you are part of (you can omit this if you won’t synchronize repositories that belong to a team account), the information from your repositories (necessary for accessing the commit data) and management of your webhooks, which we will use to create and delete webhooks when you create or delete repository integrations from HacknPlan, keeping everything in sync. You can revoke this app password whenever you want, but we recommend keeping it active, so we can safely remove the webhooks we create or other future features we will add to our BitBucket integration. Once created, you need to copy the generated password and paste it into the integration dialog in HacknPlan. Be careful, you won’t be able to access the password from BitBucket again (nor from HacknPlan) for security reasons.

Note: Although OAuth2-based authentication is available for BitBucket (the authentication method we use for the other integrations), we decided to go for the app password approach because the OAuth2 one does not work with accounts that use 2-factor verification.

Entering the credentials

When you paste the password into the field on the dialog, it will be validated (along with the username) and, if correct, a list of the BitBucket repositories you are an admin of will be added to the dropdown below. Select your desired repository and click Connect. Your integration is ready!

The Process existing commits checkbox allows you to tell HacknPlan the repository you are integrating may have task references already (maybe you integrated it before and then deleted it, or you had this feature with another service…). If checked, right after the integration all the commits in the repository will be analyzed looking for tasks referenced in the messages.

Testing the integration

Your integration is now configured, let’s check if everything is working fine. You just need to push a commit that includes the reference to an existing HacknPlan task in the message, for instance:

Integration test for task hnp-1

Note: Make sure to use the reference prefix you set in the integration configuration.When HacknPlan receives the notification of the push of that commit, the message is analyzed looking for references to work items, and the commit is added to all of them. Then, you can check the commits in the Source Code section of the task details panel. And remember, clicking on each one of the commits will take you to the details in BitBucket!