Creating links from commit comments

Edit online

When Git commits are pushed, the work item references are extracted from the commit comment.

The work item references use a specific format - the comment 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 comments:

fix workitem 123 and test
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.

In GitHub and GitHub Enterprise, # is not a supported keyword for all supported webhook events. You can add the query parameter ignoreHashAsWIKeyword=false to the webhook configuration to recognize # as a keyword. For example, the following web hook URL is configured to recognize # as a keyword because ignoreHashAsWIKeyword=false is added: 
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:

git config -global rtc.wikeywords "ticket,issue"

The above command adds ticket and issue as two new work item keywords. After you define the keywords, you can have comment 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 comment

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 comments by defining a Git configuration property called rtc.ignoreworkitemsfromcomment. The value of this property is true or false. The following command shows how to define the property: git config -global rtc.ignoreworkitemsfromcomment 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.