Creating links from commit message

Edit online

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:

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.

Note:

  • 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.

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&amp;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 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.