“Why was this change made again?” Issue keys referenced in commit messages help answer this question by providing a link with more context around why a particular change was made. They’re useful for everyone from new team members getting their bearings with a repo, to quality engineers reviewing the latest release, or a budding startup getting back to their weekend project.
Issue key references are so important that some teams need every commit to include a reference. These teams rely on issue keys to maintain diligent documentation or to automatically generate release notes or changelogs to verify every change. Historically, they could do this with pre-commit Git hooks on each developer's machine to validate messages, but this solution adds a layer of overhead that becomes difficult to manage. For these organizations, we’re introducing the ability to require issue keys for commits in Bitbucket Cloud.
Required issue keys in Bitbucket Cloud
Requiring issue keys ensures each change links to an issue in commit messages. Bitbucket automatically converts mentioned issue keys (e.g. ‘PROJ-1234’ or ‘#1234’) into links to your issue tracker so it’s easy to stay coordinated between a change and its backstory.
Issue keys aren’t just a reference. They can be used to automate workflow actions: you can add comments or transition an issue to a different state just by mentioning it, making it easier for your team to go back historically for validation of changes. If you combine this with the new JIRA issue details view, you can view and comment on JIRA issues without even leaving Bitbucket. As a result, including issue keys has become a best practice and requiring them in commit messages will make it easier to scale your workflow.
Get started with required issue keys
If you’re new to Bitbucket, sign up for a Bitbucket Cloud account. If you’re an existing Bitbucket user and are already using JIRA Software, make sure it’s connected to Bitbucket. This connection enables Bitbucket to automatically link to your JIRA Software issues. If you’re using the Bitbucket issue tracker, issues are already linked automatically.
Then, navigate to the "Links" section of your repository settings and enable “Require issue keys in commit messages."
Once enabled, Bitbucket will only accept pushes to your repo if all pushed commit message contain issue keys.
Once all commit messages include keys (e.g. using interactive rebase to update the message), the push will succeed, and the issue keys are automatically linked across Bitbucket, like in this pull request.
Not using JIRA Software and Bitbucket together?
JIRA Software is the preferred issue tracker of over 350,000 Bitbucket teams. Teams who have JIRA Software and Bitbucket integrated release 14% more often and close 23% more issues (when compared to teams using just one of those products).
Learn more.
Have more specific questions about this post? Reach out to us on Twitter to get the information you need.
