Commit checker for Jira issues

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

This feature is available with a Bitbucket Data Center license.

Ensure Jira issues in Bitbucket Data Center are tracked by creating a requirement that validates whether they exist in commit messages.

The commit checker will make sure that Jira issues exist in:

  • every commit that is pushed to a repository

  • the commit created when a pull request is merged

Depending on how you set up your requirement, when a user pushes a commit without typing a Jira issue key into the commit message, they will be stopped and alerted as to why they cannot commit the file.

You can create exemptions to skip validation on commits that contain particular terms, or were pushed by specific users. 

On this page:

Getting started

While configuring your requirement, you can run validation on commits that look for Jira issue keys typed into the commit message. You can also choose to validate that the issues placed in commit messages also actually exist in Jira.

In order to validate Jira issues in commits that exist in Jira, Bitbucket Data Center must be linked to Jira. Learn how to link to Jira.

Users can authorize specific Jira sites from Profile picture > Manage account > Authorized applications.

Project links (optional)

You can prioritize checking issues in a specific Jira by linking your Bitbucket project to your Jira project using Project Links. This means that everything in the project will be prioritized for that Jira, reducing the time used for validation. Learn how to create project links across applications.


Your requirements can be set up at the project or repository level (requires admin permissions). Any repository can inherit its project settings.

To configure and customize the commit checker at the repository level (requires repository admin permissions):

  1. Go to Repository settings > Jira issues (under Workflow)

  2. From Project settings inheritance, select Use custom settings.

  3. Select which Jira issues requirement to use:

    • Don’t need a Jira issue key - use this option to skip verifying Jira issues in commit messages for this repository.

    • Must contain a Jira issue key - use this option to set a requirement for verifying Jira issues exists in commit messages for this repository.

    • Must contain a Jira issue key that exists in Jira - use this to set a requirement for verifying Jira issues exist in commit messages for this repository and that they exist in your Jira site.

      • NOTE: Choosing this option may impact Git push performance due to each push requiring a query being made to Jira before the push can be accepted.

  4. Set up any exemptions you’d like to use. 

  5. Select Save.


You can set exemptions that will not validate those commit messages that contain specified terms or certain users who push commits.

  • Terms - type in any terms here to have the check ignore the validation of Jira issues if a commit message uses any of these. NOTE: These terms are case sensitive.

  • Users - add any users (pushers) to have the check ignore the validation of Jira issues if a commit message is created by any user that has pushed a commit.

Exclude merge commits

Enabled by default, merge commits will be excluded from commit requirements. This includes merge commits pushed through the command line and merges made via the pull request UI (squash merges will always be checked).

To include merge commits in your requirement: 

  1. Select Jira issues (under Workflow) from a project or repository’s settings.

  2. Clear the checkbox next to Skip validation of Jira issues on merge commits.

Why doesn’t the commit checker work?

The commit checker doesn’t work when commits are sent from a Bamboo build with an SSH key, created as part of the integration between Bitbucket and Jira with OAuth impersonation. This happens because service user accounts for each SSH key are created automatically and therefore, they don’t exist in external user directories like LDAP. As a result, these accounts can’t be used to authenticate against other services.

If you’re facing this issue, you can use the following workaround to set the correct user context. Create a real user in your user directory and add an SSH key to this user. Then, use this SSH key from Bamboo to push to Bitbucket.

Last modified on May 15, 2024

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.