Require Commits to be Associated with a Valid Jira Issue

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

If you use a pull request workflow, there is a merge check version of this which is simpler to use.

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.

Finally, if your Jira issue keys do not follow the following default regex format, resulting in for example JIR-1 being validated by the hook:


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

An example, which would result in JIR.1 being validated by the hook is:


Require Each Commit to be Associated with a Valid Jira Issue

It may be desirable for each commit to be associated with at least one Jira issue, 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, pushes will be blocked if the push contains a commit that does not reference at least one Jira issue.

On this page