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 workitem, work item, work-item, item, issue, feature, defect, ewm, story, epic, testplan, test plan, test-plan, ccb, bug, task, wi, rtcwi, and #. Although # is a supported keyword, do not use it if your Git hosting server can interpret #.
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.
-
When creating links from commit message by using post-receive and webhook, follow the following format.
<Special_characters_before_identifying_keyword><Workitem><Seperator><Workitem_number><Special_characters_after_identifying_workitem_number>
Where,- <Special_characters_before_identifying_keyword>
- Either hyphen (-), equal (=), colon (:), white space ( ), underscore (_), dot (.), comma (,), semicolon (;) or beginning text of the message.
- <Workitem>
- Either workitem, work item, work-item, item, issue, feature, defect, ewm, story, epic, testplan, test plan, test-plan, ccb, bug, task, wi, or rtcwi.
- <seperator>
- Either hyphen (-), underscore (_), colon (:), equal (=) or white space ( ).
- <workitem_number>
- The identifying numerical value of the work item.
- <Special_characters_after_identifying_workitem_number>
- Either hyphen (-), equal (=), colon (:), white space ( ), underscore (_), dot (.), comma (,), semicolon (;) or ending text of the message.
For example:
abc -workitem 11.
,:story 11:
,defect 11.
,test =task 11;
,test bug 11. commiting
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 preceding 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 preceding command.