Links allows commit messages and pull request comments in Bitbucket Cloud to reference pages on external sites and services. These references typically take the form of hypertext links.
From the Links page, you can set up a link between Bitbucket and any external service. By default, we provide options for Jira, Bamboo Server, Crucible, and Jenkins, making it easy to link to any of those from Bitbucket.
When you set up links, they only work for adding links to pages in Bitbucket. To view commit messages within the external service, you'll need an add-on from the Atlassian Marketplace that provides the integration.
You might see three different type of links on this page:
- Links you add from the Repository link dialog
- Connect add-ons that appear automatically when you install one
- Bitbucket issue tracker, which appears automatically when you enable the issue tracker on a repository
Require linked issue keys in commits
When you link to an issue tracking service, you can require that your users enter an issue key for every commit. To do so, toggle the Require issue keys in commit messages option. When this option is selected, users who try to push to this repository without an issue key in any of their commit messages get an error informing them that they have to add issue keys before they can push.
To see the Require issue keys in commit messages option, you must add at least one link to an issue tracker service, as explained in the next section.
Link your repository to an external application
To establish a link, you need to supply a server URL and a key. Then, you'll use that key and a value to create links on commit messages and pull request comments. If your commits or comments already include a key and value for service not yet linked, adding the service to the Links page makes them links.
- From Repository settings, click Links from the left navigation.
- Click Add new link.
The Repository link dialog appears.
- Select the Link type. If you want to link Jira, Bamboo Server, Crucible, or Jenkins, select the appropriate option. Otherwise, select Custom.
- Enter the Link URL.
For example, if you're linking to Jira, your URL may look like https://jira.atlassian.com.
- Enter the Link key. The key value is case sensitive.
For example, if you're linking to a project in Jira with a key of BB, you'll enter BB for the key.
- Press Save.
To use the link once it's set up, you reference the Link key and a value from the service. For example, if you want to link to issue 5792 in the BB project of your Jira instance, enter
BB-5792 in the commit message:
hg commit -m "BB-5792 Profile page website opens in a new window/tab"
You'll these see the issue key appear as a link on the Commit page:
If you mistyped the issue key or made any other mistakes in your commit message, you will need to amend the commit. For more information on amending a commit message, see our Rewriting history tutorial.