Configuring ref-update hooks

To enable process enforcement between Gerrit and IBM® Engineering Workflow Management (EWM), 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 and set the following environment variables:
    Environment variable Description
    NODE_EXECUTABLE 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_TOOLKIT_PATH Absolute path to the folder where the EWM Git Integration Toolkit has been installed.
    RTC_GIT_SERVER_TRACE_LEVEL 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.
  4. For Linux or Unix systems, mark the ref-update script as executable by running the following command: chmod +x ref-update.
  5. Set the Git configuration properties and for the operating system user who owns the Gerrit process.

video icon Video channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community forums library

support icon Support

IBM Support Community
Deployment wiki