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 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:

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

Note:

  • When creating links from commit message using post-receive hook, follow the below format.

    <any text or space>workitem<whitespace><workitem_number><seperator>

    Where,
    <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.
    All the keywords such as bug, task, defect, workitem, wi, rtcwi will work.

    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,
    <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.
    All the keywords such as bug, task, defect, workitem, wi, rtcwi will work.

    For example: test workitem 11 testing, test workitem 11:, test workitem 11[, test workitem 11{