Configuring ref-updated hooks to link Git commits to Engineering Workflow Management work items

To enable linking work items to Git commits, configure a ref-updated hook. Perform this task only once for a Gerrit server.

Before you begin

A shared user base, such as a common LDAP, between Engineering Workflow Management and the Gerrit server is optional. It is recommended to add an Engineering Workflow Management functional user ID to the post-receive hook configuration by setting the REMOTE_USER variable. Ensure that the functional user is authorized for Git requests.

About this task

The Gerrit Node.js based hooks are under RTC Git toolkit\server\hooks\examples\gerrit. The Gerrit hooks use the following scripts:

For Windows systems, use ref-updated.bat.
For UNIX systems, use ref-updated.

Procedure

Copy the script to the Gerrit-installation-location/hooks folder.

Important: If hooks scripts exist, then manually merge these hook scripts with the existing scripts.
Add the following entries to the Gerrit configuration file, which is at Gerrit-installation location/etc/gerrit.config.
- For Windows systems:
```
[hooks]
       refUpdatedHook = ref-updated.bat
```
- For UNIX systems:
```
[hooks]
        refUpdatedHook = ref-updated
```
Open the ref-updated script in a text editor.

Uncomment and set the following mandatory variables:

Variable	Description
RTC_GIT_SERVER_TOOLKIT_PATH	Absolute path to the folder where the Engineering Workflow Management Git Integration Toolkit has been installed.

You can also uncomment and set the following optional variables:

Variable	Description
NODE_EXECUTABLE	Optional: Absolute path to the node executable. Required if the node executable cannot be found in the system path. Uncomment the variable and set the value.
REMOTE_USER	Optional: If Engineering Workflow Management and Gerrit do not share a common user base, then provide a functional user ID. This user ID should be a valid Engineering Workflow Management user. Set this variable to enable only linking between Git commits to Engineering Workflow Management work items and not enable process preconditions and permissions for Git push operation.
RTC_GIT_SERVER_TRACE_LEVEL	Optional: Logging level for the hooks. Set this value to `4` while you up the integration. Revert it after you validate the integration. Uncomment the variable and set the value.

For Linux or Unix systems, mark the ref-updated script as executable by running the following command: chmod +x ref-updated.
Set the Git configuration properties user.name and user.email for the operating system user who owns the Gerrit process.