Configuring ref-update hooks

To enable process enforcement between Gerrit and IBM® Engineering Workflow Management (Engineering Workflow Management), configure a ref-update hook on the Gerrit server. Perform this task only once for a Gerrit server.

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-update.bat.
  • For UNIX systems, use ref-update.


  1. 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.
  2. Add the following entries to the Gerrit configuration file, which is at Gerrit-installation location/etc/gerrit.config.
    • For Windows systems:
             refUpdateHook = ref-update.bat
    • For UNIX systems:
              refUpdateHook = ref-update
  3. Open the ref-update script in a text editor.
  4. 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.
    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.
  5. For Linux or Unix systems, mark the ref-update script as executable by running the following command: chmod +x ref-update.
  6. Set the Git configuration properties and for the operating system user who owns the Gerrit process.