HashiCorp Cloud Platform
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.
Note
The CLI must be uploaded as a regular file and not Git LFS file. LFS files are not properly checked out by GHES and the hook will fail.
Note
Set the git config http.postBuffer 157286400
option might to increase the buffer size for large files.
Create new chroot environment
Overall GHES instructions are here.
Below are steps to create a new chroot environment based on the guide above.
Download a version from https://releases.hashicorp.com/vault-radar/
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/
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
Then upload
github-pre-receive.alpine.tar.gz
to GHES.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
Note
The license and config file could be part of the hook environment, similar to CLI itself. But having them in repo simplifies the setup.
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.