Bitbucket Server でカスタム Jira 課題キーに連携する
問題
JIRA has a UI to help specify a custom issue key format. When integrating with Bitbucket Server, these custom JIRA issue keys are not recognized by Bitbucket Server, and hence commits are not linked to the JIRA issues.
原因
Bitbucket Server passes commit messages through a regex pattern to identify and create links. The default format is two or more uppercase letters ([A-Z][A-Z]+), followed by a hyphen and the issue number (e.g. "TEST-123").
This regex for matching Jira issue keys has changed over time, multiple versions are provided below.
(?<=^|[a-z]\-|[\s\p{Punct}&&[^\-]])([A-Z][A-Z0-9_]*-\d+)(?![^\W_])
Note: with this pattern, issue keys are recognized if they are preceded by any of the following:
- beginning of a line
- a lowercase letter followed by a dash
- whitespace or punctuation character, excluding a dash
((?<!([A-Z]{1,10})-?)[A-Z]+-\d+)If a custom issue key format is specified in JIRA, the custom format also needs to be configured in Bitbucket.
ソリューション
Follow the steps below to modify the regex pattern:
1) Shut down Bitbucket Server.
2) Edit the contents of the <Bitbucket Server installation directory>/bin/setenv.sh or <Bitbucket Server installation directory>/bin/setenv.bat (depending upon your OS) and add the modified regex to the variable JVM_SUPPORT_RECOMMENDED_ARGS.
3) Save the file.
4) Remove the contents of the following folder:
| バージョン | Folder location |
|---|---|
| Up to 2.10.x | <BITBUCKET_HOME>/caches/idx-snapshots |
| 2.11 以降 | <BITBUCKET_HOME>/data/snapshots |
| 3.2 以降 | <BITBUCKET_HOME>/shared/data/snapshots |
5) Restart Bitbucket Server.
6) Push to the repository with the JIRA issue key in the commit message to force a reindex of the data.
For example, to match JIRA keys such as C001-1 or ABC123-1, set the variable as follows:
2.8 よりも前
JVM_SUPPORT_RECOMMENDED_ARGS="-Dstash.jira.key.pattern=\"((?<!([A-Z0-9]{1,10})-?)[A-Z0-9]+-\d+)\""2.8 以降
JVM_SUPPORT_RECOMMENDED_ARGS="-Dintegration.jira.key.pattern=\"((?<!([A-Z0-9]{1,10})-?)[A-Z0-9]+-\d+)\""
5.0 以降
JVM_SUPPORT_RECOMMENDED_ARGS="-Dintegration.jira.key.pattern=((?<!([A-Z0-9]{1,10})-?)[A-Z0-9]+-\d+)"To match JIRA both uppercased and lowercased JIRA keys, set the variable as follows:
JVM_SUPPORT_RECOMMENDED_ARGS="-Dintegration.jira.key.pattern=\"(?<=^|[a-z]\-|[\s\p{Punct}&&[^\-]])([a-zA-Z][a-zA-Z0-9_]*-\d+)(?![^\W_])\""5.0 以降
JVM_SUPPORT_RECOMMENDED_ARGS="-Dintegration.jira.key.pattern=(?<=^|[a-z]\-|[\s\p{Punct}&&[^\-]])([a-zA-Z][a-zA-Z0-9_]*-\d+)(?![^\W_])"Bitbucket Server 5.0+ では setenv と環境変数に変更があります
Bitbucket Server 5.0 以降では setenv.sh と setenv.bat が取り除かれています。これらのファイルで設定されていたオプションは、環境変数で設定できるようになりました。環境変数の設定場所は、実行先のオペレーティング システムに応じます。
Linux
When using the atlbitbucket service on Linux, the environment variables are ignored. You must set the parameters in _start-webapp.sh (or start-bitbucket.sh). These values will be read when the service starts.
たとえば、 JVM_SUPPORT_RECOMMENDED_ARGS を設定するには、ファイルに次の行を追加します。
JVM_SUPPORT_RECOMMENDED_ARGS=-XX:+HeapDumpOnOutOfMemoryErrorWindows
Bitbucket Server を実行しているユーザーで、パラメーターを環境変数として設定します。たとえば、JVM_SUPPORT_RECOMMENDED_ARGS を設定したい場合、それを環境変数として作成して適切な値を割り当てます。Bitbucket Server がスタートアップ スクリプトやサービスを利用して起動する際に、この値が取得および適用されます。
If the parameter is set correctly the following line will be logged in the <BITBUCKET_HOME>/log/atlassian-bitbucket.log:
c.a.i.i.jira.PatternJiraKeyScanner Using custom Jira key pattern: ((?<!([A-Z0-9]{1,10})-?)[A-Z0-9]+-\d+)Or the following in older versions of Bitbucket Server:
c.a.s.i.jira.idx.JiraKeyIndexer Using custom JIRA key pattern: ((?<!([A-Z0-9]{1,10})-?)[A-Z0-9]+-\d+) the regex in Bitbucket Server does not match exactly the one specified in JIRA, in Bitbucket Server it is required to add the -\d suffix to the JIRA one
Changing the Jira key pattern here does not affect the hyperlinks generated on commit messages, but only the indexed commit messages that are gathered to display issues in the 'Issues' column.
See the following for more details:
- BSERV-10930 - Getting issue details... STATUS