Require Commits to be Associated with a Valid Jira Issue

This requires either branch name or each commit message to reference a valid Jira issue, where the supplied JQL query defines what’s valid.

If you use a pull request workflow, then a merge check version is available.

A configured Jira application link is required. You either have to make one of your application links primary or select one when configuring this hook, as in the image below. If you select multiple application links then each one will be queried until one returns issues which match the specified JQL clause.

If you remove an application link you have selected for the hook, you should also update the hook configuration. As the hook verifies the application link can be found. If you don’t the hook will fail when you push to it.

A sample query might be:

  • The issue is "in progress" and assigned to the user pushing the changes:


status = "In Progress" and assignee = currentUser()

  • You could also require that each commit references a particular Jira project:


project = FOO

If the hook rejects the push, the user will need to edit the commit comments (for instance using git rebase) before pushing again.

If you want to exclude merge commits from being checked then you should select the exclude merge commits checkbox when configuring the hook.

You can also build a dynamic JQL clause to query on. You can either create your own templates or use one of the samples that are included in the default installation of ScriptRunner.

Issue key regex

You can specify your own issue key regular expression using the "Issue key regex" field.

For example, if JIR.1 is a valid Jira key, you should use a custom regex such as:


((?<!([A-Z]{1,10})\.?)[A-Z]+\.\d+)

If you leave this field blank, and you have set a custom Jira issue key pattern in the Bitbucket server settings, then the hook will use that pattern.

If you have not specified a custom regex in the Bitbucket server settings, then the default format will be used, matching any issues with the default 'JIR-1' format.


((?<!([A-Z]{1,10})-?)[A-Z]+-\d+)

Require Each Commit to be Associated with a Valid Jira Issue

It may be desirable to just check for each commit to be associated with at least one Jira issue and ignore the branch name, this can be useful for tracking all commits back to a Jira issue.

This restriction can be optionally enabled for the pre-hook by checking the Require Valid Jira Issue in Every Commit? checkbox. With this checkbox checked, regardless of whether the branch name contains a valid Jira issue, pushes will be blocked if the push contains a commit that does not reference at least one Jira issue.

On this page