Using custom Jira issue keys with Bitbucket Server

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

Bitbucket Data Center and Server assumes that Jira Software issue keys are of the default format (that is, two or more uppercase letters ([A-Z][A-Z]+), followed by a hyphen and the issue number, for example TEST-123). By default, Bitbucket will not recognize custom issue key formats.

You can use custom issue key formats with Bitbucket, however note that integrations with Jira Software can depend on using the default issue key format in both applications. See Integrating using custom Jira Software issue keys for more details.

Configure Bitbucket to recognize custom issue key formats by editing <Bitbucket installation directory>/bin/_start-webapp.sh (on Windows, _start-webapp.bat).

To override the default issue key format, use the JVM_SUPPORT_RECOMMENDED_ARGS property, like this:

JVM_SUPPORT_RECOMMENDED_ARGS="-Dintegration.jira.key.pattern=\"(<Some different regex>)\""

You'll need to restart Bitbucket.


For example, to use lowercase letters in issue keys, use a regex with the parameter like this:

'-Dintegration.jira.key.pattern=(?<=^|[a-z]-|[\s\p{Punct}&&[^-]])([a-z]{1,10}-\d+)(?![^\W_])'

See also Reindex Jira Software issue keys.

When a custom Jira pattern is specified using Dintegration.jira.key.pattern, it does not affect the JavaScript regex used to create hyperlinks on commit messages and in other areas.

As always, be sure to back up your home directory (and perhaps the database) before performing any manual operation on Bitbucket. Consider testing this change on another copy of Bitbucket before using it in production.

Last modified on May 9, 2022

Was this helpful?

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