A pre-receive environment for GitHub Enterprise Server is a Linux chroot
environment. Because pre-receive hooks execute on every push event, they should be fast and lightweight. The environment needed for such checks will typically be minimal.
GitHub Enterprise Server provides a default environment which includes these packages: awk
, bash
, coreutils
, curl
, find
, gnupg
, grep
, jq
, sed
.
If you have a specific requirement that isn't met by this environment, such as support for a particular language, you can create and upload your own 64-bit Linux chroot
environment.
The Git version used in the pre-receive hook environment must be at least 2.11, or if you are using libgit2 you must use at least version 0.18.
If you are using another Git implementation, it must support relative paths in the info/alternates
file.
Creating a pre-receive hook environment using Docker
You can use a Linux container management tool to build a pre-receive hook environment. This example uses Debian Linux and Docker.
-
Ensure Docker is installed locally.
-
Create the file
Dockerfile.debian
that contains this information:FROM --platform=linux/amd64 debian:stable RUN apt-get update && apt-get install -y git bash curl RUN rm -fr /etc/localtime /usr/share/zoneinfo/localtime
Note
The Debian image includes some symlinks by default, which if not removed, may cause errors when executing scripts in the custom environment. Symlinks are removed in the last line of the example above.
-
From the working directory that contains
Dockerfile.debian
, build an image:$ docker build -f Dockerfile.debian -t pre-receive.debian . > [+] Building 0.6s (6/6) FINISHED docker:desktop-linux > => [internal] load build definition from Dockerfile.debian > => [1/2] FROM docker.io/library/debian:latest@sha256:80dd3c3b9c6cecb9f1667e9290b3bc61b78c2678c02cbdae5f0fea92cc6 > => [2/2] RUN apt-get update && apt-get install -y git bash curl > => exporting to image > => => exporting layers > => => writing image sha256:b57af4e24082f3a30a34c0fe652a336444a3608f76833f5c5fdaf4d81d20c3cc > => => naming to docker.io/library/pre-receive.debian
-
Create a container:
docker create --name pre-receive.debian pre-receive.debian /bin/true
-
Export the Docker container to a
gzip
compressedtar
file:docker export pre-receive.debian | gzip > debian.tar.gz
This file
debian.tar.gz
is ready to be uploaded to the GitHub Enterprise Server appliance.
Creating a pre-receive hook environment using chroot
-
Create a Linux
chroot
environment. -
Create a
gzip
compressedtar
file of thechroot
directory.cd /path/to/chroot tar -czf /path/to/pre-receive-environment.tar.gz .
Note
- Do not include leading directory paths of files within the tar archive, such as
/path/to/chroot
. /bin/sh
must exist and be executable, as the entry point into the chroot environment.- Unlike traditional chroots, the
dev
directory is not required by the chroot environment for pre-receive hooks.
- Do not include leading directory paths of files within the tar archive, such as
For more information about creating a chroot environment see Chroot from the Debian Wiki or BasicChroot from the Ubuntu Community Help Wiki.
Uploading a pre-receive hook environment on GitHub Enterprise Server
-
In the top-right corner of GitHub Enterprise Server, click your profile photo, then click Enterprise settings.
-
On the left side of the page, in the enterprise account sidebar, click Settings.
-
Under " Settings", click Hooks.
-
Click Manage environments.
-
Click Add environment.
-
In the "Environment name" field, enter the desired name.
-
In the "Upload environment from a URL" field, enter the URL of the
*.tar.gz
file that contains your environment. -
Click Add environment.
Uploading a pre-receive hook environment via the administrative shell
-
Upload a readable
*.tar.gz
file that contains your environment to a web host and copy the URL or transfer the file to the GitHub Enterprise Server appliance viascp
. When usingscp
, you may need to adjust the*.tar.gz
file permissions so that the file is world readable. -
Connect to the administrative shell.
-
Use the
ghe-hook-env-create
command and type the name you want for the environment as the first argument and the full local path or URL of a*.tar.gz
file that contains your environment as the second argument.admin@ghe-host:~$ ghe-hook-env-create DebianTestEnv /home/admin/debian.tar.gz > Pre-receive hook environment 'DebianTestEnv' (2) has been created.