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 merge check, 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 merge check, you should also update the merge check configuration. As the merge check verifies the application link can be found. If you don’t the merge check will fail.

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.

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 merge check 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]\-|[\s\p{Punct}&&[^\-]])([A-Z][A-Z0-9_]*-\d+)(?![^\W_])


Require Each Commit to be Associated with a Valid Jira Issue

It may be desirable just to check for each commit to be associated with at least one Jira issue and ignore the pull request title. 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. When checked, regardless of whether the pull request title contains a valid Jira issue, merges will be blocked if the pull request contains a commit that does not reference at least one Jira issue.


On this page