Require That a Pull Request is Associated with a Valid Jira Issue

This requires the pull request to reference a valid Jira issue, where the supplied JQL query defines what’s valid. The issue can either be mentioned in the pull request title, or be present in one of the commit messages comprising the pull request. See also the version that works on push.

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.

jira application link selection

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 attempting to merge the pull request:

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

  • You could also require that the pull request references a particular Jira project:

project = FOO

If the merge check doesn’t allow the merge, the user will need to edit the pull request title, or rebase and push.

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.

Can Only Merge to a Valid Release Branch

The following JQL clause template ensures that the target branch name corresponds to a fix version in Jira before merging.


fixVersion = '${mergeRequest.pullRequest.toRef.displayId}'


This enforces that any changes can be traced back to a particular release through Jira.


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 merge check by checking the Require Valid Jira Issue in Every Commit?checkbox. With this checkbox checked, the merge of the pull request will be blocked if any commit exists without at least one valid Jira issue referenced in the commit message.

On this page