GitHub pre-receive hook

Setting up and configuring pre-receive hooks is tightly coupled with the server implemenation, as a result it may be helpful to refer to the GitHub documentation for more information. The following is an example of how to set up a pre-receive hook using vault-radar for GitHub Enterprise Server (GHES).

Install vault-radar

The vault-radar CLI has to be installed or uploaded to the GitHub server where the hook will be run. There are a few ways this can be done. The easiest is to include the binary in the same repository where the hook script is saved.

Alternatively, the CLI can be installed in a chroot environment. This way the CLI will be a part of the chroot environment and will be available as a global command in the pre-receive script.

Commit the CLI as part of the repo

This is done by putting the CLI binary in the hook repository itself.

Create new chroot environment

Overall GHES instructions are here.

Below are steps to create a new chroot environment based on the guide above.

1. Download a version from https://releases.hashicorp.com/vault-radar/

2. Create a ./Dockerfile.pre-receive-env similar to the one below:

   FROM alpine:3.3
   RUN apk add --update --no-cache git bash
   
   # TARGETARCH and TARGETOS are set automatically when --platform is provided.
   ARG TARGETOS
   ARG TARGETARCH
   
   COPY dist/linux/$TARGETARCH/vault-radar /bin/
   

3. Use ./Dockerfile.pre-receive-env as a base image and add the CLI to it:

   $ docker build -f ./Dockerfile.pre-receive-env -t github-pre-receive.alpine --platform=linux/amd64 .
   
   $ docker create --name github-pre-receive.alpine github-pre-receive.alpine /bin/true
   
   $ docker export github-pre-receive.alpine | gzip > github-pre-receive.alpine.tar.gz
   

4. Then upload github-pre-receive.alpine.tar.gz to GHES.

5. After that it can be imported as new GHES hook environment in Settings > Pre-receive environments.

Hook repo

on GHES, pre-receive hooks is stored in a Git repository. The repo must contain:

• the hook script itself
• the vault-radar license
• the vault-radar config file
• optionally the CLI binary

Example hook script

Here is an example of a hook script used in a GitHub Enterprise Server environment:

#!/bin/bash

git=$(which git)
export GIT=$git

# Get the directory of the script
# this is needed to properly pass the location of the license file and config file to vault-radar
script_dir=$(dirname "$(realpath "$0")")

# Set the HOME environment variable to the githook user's home directory
# on GHES hook env HOME var is not set
# without it vault-radar will fail  
export HOME=/home/githook

export VAULT_RADAR_LICENSE_PATH=$script_dir/vault-radar.hclic
export VAULT_RADAR_CONFIG_PATH=$script_dir/config.json

exec $script_dir/vault-radar scan git pre-receive

The script above will use vault-radar executable, license and config from the repo.