Verigreen Hook Deployment

The Verigreen hook a pre-receive git hook that communicates all push operations to the Verigreen collector. The verigreen collector detects any pushes to one of its protected branches. Then, the Verigreen hook:

• Creates a new temporary branch for the newly pushed commit
• Rejects the commit with a notification that the push was submitted for verification by Verigreen.

Please follow below instructions to deploy the Verigreen hook, and configure it to communicate with the Verigreen collector.

Requirements

• A git provider supporting synchronous pre-receive hooks.
• Java 7 version 55+. Java 8 is not supported as yet.
• tar or 7zip.

Downloadable Hook Files

Please download the following files. The Installation section below targets Linux-based systems and contains the commands to download the required files.

1. The latest hook binaries are here
2. Shell scripts are recommended when configuring pre-receive hooks. The Verigreen repository contains the following sample scripts:
   • A Linux shell script.
   • A Windows batch script.
     The Gitblit git provider is using Groovy, and thus has its own script:
   • A groovy script for Gitblit.

Installation

Hook Files

1. Extract the hook files from the tar. Verify the user running the git provider can execute the jar file(s).
   For this example the /opt/verigreen/ folder will be used.
   Note: The user which is used to run the git provider (Bitbucket Server/Gitblit/GitLab/etc.) must have execute permissions for the hook files.
   mkdir /opt/verigreen/2.5.6
cd /opt/verigreen/2.5.6
wget https://github.com/Verigreen/verigreen/releases/download/verigreen-2.5.6/verigreen-git-hook.tar.gz
tar -xzf verigreen-git-hook.tar.gz
chmod 755 .
2. Modify the hook.properties file. The files contains one parameter - the Verigreen collector address.
   vi hook.properties
   Set collector.address to the URL of the collector using this format: http://{collectorHost}:{collectorPort}/rest.

Set Up A Pre-Receive Hook

1. Change into the required folder to hold the pre-receive hook.
   • For Atlassian Bitbucket Server, a sample folder would be: /home/username/bitbucket_home, or as set within the BITBUCKET_HOME environment variable. The BITBUCKET_HOME is configured with the setenv file, located under: {Bitbucket Server installation folder}/bin/setenv.
   • For Gitblit, the groovy script need be placed under {Gitblit installation folder}/data/groovy.
2. Download the required shell/groovy pre-receive script as per above.
3. If needed, set run permissions for the user running the git provider. chmod +x {pre-receive script}
4. Configure the pre-receive script by setting:
   • JAVA_HOME="{JAVA_HOME_PATH}"
   • VG_HOOK="{Path_to_Verigreen_hook.properties_File}"
   • VG_PATH="{Path_to_Verigreen_git-hook.jar_File}"
     Note:
   • All variables must contain folder names, not file names.
5. Within the git provider, enable/configure a pre-receive hook for the required repository.
   The hook must supply the repository name as its first parameter. This is set up automatically for the Gitblit provider as part of the groovy script capabilities.
   • For Atlassian Bitbucket Server, we recommend using the External Hooks Plugin. Note that Bitbucket Server Sysadmin previliges are required to enable the plugin for a speific repository.

Troubleshooting

Try manually running the verigreen hoook manually, directly within the server's repository.
This example is for a Linux-based Gitblit installation, but can be adapted as needed.
The repository name is MyRepo, and the protected branch is refs/heads/master.
cd /opt/gitblit-1.6.2\data\git\MyRepo.git
Configure VG_HOME for this session:
export VG_HOME=/opt/verigreen/2.5.6
If needed, configure JAVA_HOME as well.
echo $JAVA_HOME
export JAVA_HOME={path to Java Installation}
Set the oldrev and newrev commit IDs. These can be "fake" IDs, if only testing the hook's connection to the Verigreen collector.
export oldrev=1
export newrev=2
Set the protected branch name:
export protectedBranch=refs/heads/master
Now, run a test:
$JAVA_HOME/bin/java -jat $VG_HOME/git-hook.jar MyRepo $oldrev $newrev $protectedBranch
If all is OK, the hook will connect to the Verigreen collector and will fail to find the commit (as we didn't use a real one). If real commit IDs are used (taken from the repository branch logs), Verigreen will attempt to verify it.

In case the hook fails on collector.addrees issues:
1. Verify the Verigreen collector is up and responding.
1. Verify the value within the hook.properties is correct.
1. Verify the VG_HOME parameter is set correctly, pointing to the folder holding the hook.properties file.
1. Finally, if all else fail, place the hook.properties file in the same folder as Verigreen's git-hook.jar file, and set VG_HOME to this folder.