In this page

Overview

This page is about implementing Better Commit Policy specifically in Git repositories managed by the GitHub Enterprise application. If you use Git, but you don't use GitHub Enterprise, see the general Git guide instead of this page.

Working with GitHub Enterprise commit policies

GitHub Enterprise builds on the top of the Git version control system, extending that with repository-, user- and permission management capabilities. As it is primarily a high-level management layer above Git, everything written in the general Git guide applies to the Git repositories managed by GitHub Enterprise, too.

In the Better Commit Policy app's context, the only major difference between using Git alone and Git with GitHub Enterprise is how you install the commit hooks to the central Git repository. (Installing hooks to the local Git repositories is the same for those two cases.)

Installing GitHub Enterprise hooks

Installing GitHub Enterprise hooks for remote verification

First, read the GitHub Enterprise pre-receive hooks page to learn how to use custom hook scripts in GitHub Enterprise managed Git repositories in general.

Creating a custom environment with Docker

GitHub Enterprise executes hook scripts in managed environments. As the Better Commit Policy app's hook scripts are written in Python and the default GitHub Enterprise environment does not include the Python interpreter, you need to build a custom environment. It is rather easy using Docker, the standard container management tool, and you have to do this only once.

The instructions below will create a custom environment based on the official Docker image of Python 2 on Alpine Linux.

Steps:

  1. Install Docker (if not yet).
  2. Create a file named Dockerfile.python-2-alpine with the following content: 
    FROM python:2-alpine
RUN apk add --no-cache git bash \
	&& ln -s /usr/local/bin/python2 /usr/bin/python
  3. Build the docker image: 
    docker build -f Dockerfile.python-2-alpine -t pre-receive.python-2-alpine .
    (If you see "Got permission denied" errors at this or the next Docker commands, just run them prefixed with sudo like sudo docker build ....)
  4. Create the docker container: 
    docker create --name pre-receive.python-2-alpine pre-receive.python-2-alpine /bin/true
  5. Export the container to a ZIP file: 
    docker export pre-receive.python-2-alpine | gzip > python-2-alpine.tar.gz
  6. Upload the ZIP to the GitHub environments: 
    ghe-hook-env-create python-2-alpine /home/admin/docker/python-2-alpine.tar.gz
    (The ghe-hook-env-create tool is available on the server where GitHub Enterprise is installed.)
    Alternatively, you can make the ZIP file available at a public URL (from which GitHub can download that) and follow the instructions here. Use python-2-alpine as environment name also in this case.

Note that the environment created this way can be reused for any number of Git repositories. You would typically do this only when you install the very first hook script.

Uploading the hook script

To install the hook script for Better Commit Policy, launch the Hook Script Wizard, select "Git" as VCS, and follow the steps until 1: Unpack the ZIP file to the location where Git expects it. At this step ignore the wizard's instructions, because GitHub Enterprise provides its own feature to manage hook scripts.

Instead, follow the instructions below:

  1. As GitHub Enterprise expects also the hook scripts themselves being stored in Git repositories, create a new repository commit-policy-hooks for the hook scripts of all your actual repositories. We prefer to have a single separate repository for this purpose, because it allows isolating hook scripts from the actual source code of our projects.
  2. Within this repository, we use a separate top-level directory for the hook script of each actual repository. So, create a new directory with the name of the commit policy that you want to generate the hook for, e.g. /FOO. (This simple structure is very practical, but you can, of course, use other types of structures or can even mix the hooks with actual source code.)
  3. Extract the hook script package ZIP to this new directory.
  4. Open jcp_git_common.py in a plain text editor, and modify the method called started_manually() at the end of the file to this: 
    def started_manually():
	return False
  5. Add all files to the staging area, and make the pre-receive script executable: 
    git add .
git update-index --chmod=+x pre-receive
  6. Add all files again, commit and push the changes to GitHub Enterprise: 
    git add .
git commit -m "Add the pre-receive hook script for FOO"
git push
Configuring the hook script for the given repository
  1. Go to Site admin → Enterprise → Settings → Hooks.
  2. Click Add pre-receive hook.
  3. For the sake of simplicity, use the directory name as the hook name, e.g. FOO.
  4. Select python-2-alpine as the environment.
  5. Select the hook repository commit-policy-hooks and the pre-receive script in the FOO directory.
  6. Uncheck Enable this pre-receive hook on all repositories by default (to avoid surprises in the future).
  7. Check Owners can enable and disable this hook.
  8. Finally, go to your actual GitHub repository → Settings → Hooks.
  9. Enable the hook you just created.

When completed, commit policies will be verified both when pushing commits to GitHub Enterprise and when using the web-based file editor:

Installing GitHub Enterprise hooks for local verification

Installing the local hook to a local Git repository which was cloned from a GitHub Enterprise managed central repository is the same as installing that to any other local Git repository.

See the installing Git hooks for local verification section for detailed instructions.

GitHub Enterprise commits

In your daily developer workflow, when creating commits and pushing those to GitHub Enterprise, you can use your Git client exactly the same way as you would with Git alone.

See the Git commits section for detailed instructions.

Questions?

Ask us any time.