Creating links from commit message
When Git commits are pushed, the work item references are extracted from the commit message.
The work item references use a specific format - the commit message contains certain keywords followed by the work item numbers. The format is keyword wi-num.
Supported work item keywords
The supported keywords are rtcwi, work item, workitem, task, defect, and bug. Although # is a supported keyword, do not use it if your Git hosting server can interpret #. We recommend that you use rtcwi or workitem to refer to IBM® Engineering Workflow Management (EWM) work items.
The following examples are text fragments that are valid work item references when they occur in commit messages:
resolve rtcwi 123
In GitLab and GitHub Enterprise, you must use keyword wi-num format to specify work items in commit and issue discussions.
Considerations when using the # keyword in Gitlab and GitHub Enteprise
In GitLab, # is not a supported keyword for issue and commit dicsussions. For the push event, you can use the ignoreHashAsWiKeyword query parameter to stop recognizing # as a work item keyword. The default value is false.
https://localhost:9443/ccm/service/com.ibm.team.git.common.internal.IGitHubInvokeService?repokey=6a1e&ignoreHashAsWiKeyword=false
Defining new keywords
If you use server-side hooks (per-receive, post-receive, ref-updated), you can define new keywords, in addition to using the pre-defined keywords listed above.
Define keywords by using the Git configuration property named rtc.wikeywords. The property value is a comma-separated list of keywords. The following command illustrates how to define keywords:
The above command adds ticket and issue as two new work item keywords. After you define the keywords, you can have commit message text that contains fix for ticket 100; 100 is detected as a work item reference number.
You can create the property as a global Git configuration property, so that these keywords are applied across repositories. Otherwise, ignore the -global switch in the above command.
Suppressing detection of work item from commit message
This feature is supported only if you use server-side web hooks (post-receive, ref-updated).
If you use Git Notes to link work items to Git commits, you can instruct the server-side hooks to ignore work item references in the Git commit message by defining a Git configuration property called rtc.ignoreworkitemsfromcommitmessage. The value of this property is true or false. The following command shows how to define the property: git config -global rtc.ignoreworkitemsfromcommitmessage true.
You can create the property as a global Git configuration property if you want to suppress it across Git repositories. Otherwise, remove the -global switch in the above command.
When creating links from commit message using post-receive hook, follow the below format.
<any text or space>workitem<whitespace><workitem_number><seperator>
Where,All the keywords such as bug, task, defect, workitem, wi, rtcwi will work.- <any text or space>
- The text or space you want to add.
- <whitespace>
- An empty space.
- <workitem_number>
- The identifying numerical value of the work item.
- <seperator>
- Use either a space or a period followed by a space.
For example:
workitem 11
,testworkitem 11
,abcddefect 11.
,test abcdtask 11
,test testingbug 11. commiting
When creating links from commit message using web hooks, follow the below format.
<whitespace>workitem<whitespace><workitem_number><seperator>
Where,All the keywords such as bug, task, defect, workitem, wi, rtcwi will work.- <whitespace>
- An empty space.
- <workitem_number>
- The identifying numerical value of the work item.
- <seperator>
- Use either a space or any single special character other than a letter or a digit.
For example:
test workitem 11 testing
,test workitem 11:
,test workitem 11[
,test workitem 11{