Creating pre-receive hooks in GitHub Enterprise

You can configure a pre-receive hook in GitHub Enterprise for process enforcement with IBM® Engineering Workflow Management (EWM).

About this task

Note: A user ID between GitHub Enterprise and EWM must match for process enforcement.

GitHub Enterprise requires setting up a pre-receive hook environment and associating the environment with a pre-receive hook file. The hook file must be added to a GitHub Enterprise repository. Only Push operations are supported.

Note: If your GitHub repositories are part of a GitHub organization, then you can create one pre-receive hook that can be used for all the repositories in that organization. You can enable the pre-receive hook for all repositories in the organization or enable it on per-repository basis. Consult the GitHub Enterprise documentation for enabling pre-receive hook for an organization.

Generate an OAUTH token for the GitHub organization administrator

Procedure

  1. In GitHub Enterprise, login as the user who is the administrator of the GitHub organization.
  2. Generate a personal access token for the GitHub organization administrator. See Creating a personal access token for the command line. Select only read:repo_hook scope.
  3. Copy the token and put it into a temporary text file.

Create a docker image for the pre-receive hook environment

Procedure

  1. Download the Git Integration Toolkit.
    1. Go to https://jazz.net/downloads/rational-team-concert/.
    2. Click the appropriate release, then click the All Downloads tab.
    3. On the All Downloads page, scroll down and download the EWM Git Integration Toolkit.
  2. Create a folder for building a docker image called RTCImageForGitHub. For example: # mkdir -p ~/RTCImageForGitHub
  3. Extract the Git-server-Toolkit to this folder. For example: # unzip -d ~/RTCImageForGitHub ~/Downloads/Git-Server-Toolkit-6.0.6.zip
  4. Create a text file named token.txt and copy the personal access token that you created in the previous section. For example:
    # touch ~/RTCImageForGitHub/token.txt 
    # echo 8b5596aa832dbf065800bf69bbc3ac1e715ab39d > ~/RTCImageForGitHub/token.txt 
    # cat ~/RTCImageForGitHub/token.txt 
    8b5596aa832dbf065800bf69bbc3ac1e715ab39d
  5. Create a file called Dockerfile in the RTCImageForGitHub folder and copy the following contents to it.
    FROM gliderlabs/alpine:3.3
    RUN apk add --update --no-cache bash make git nodejs python
    COPY server /usr/share/githooks/server
    COPY license /usr/share/githooks/license
    COPY info /usr/share/githooks/info
    COPY token.txt /opt/github/token.txt
    RUN cd /usr/share/githooks/server && npm install --production
    Note: Be sure to use the Docker image that is suggested by GitHub Enterprise as the base Docker image. The image shown in this step has been taken from Creating a pre-receive hook environment using Docker.
  6. Build a new Docker image from the Dockerfile in the folder ~/RTCImageForGitHub. For example:
    # cd ~/RTCImageForGitHub
    # docker build --tag rtc-github-image-for-prereceive . 
    Note: Be sure to include the period (.) at the end of the command.
  7. Create a container from the Docker image that you created in the previous step and run a bash shell. For example: # docker run -i -t --name test-container rtc-github-image-for-prereceive:latest /bin/bash

    Upon executing the command, the prompt switches to the bash shell in the container’s context.

  8. Inside the new shell, run the following commands to ensure that the required packages (bash, make, sed, git, node.js and python) are installed.
    bash-4.3# which bash
    /bin/bash
    bash-4.3# which make
    /usr/bin/make
    bash-4.3# which git
    /usr/bin/git
    bash-4.3# which node
    /usr/bin/node
    bash-4.3# which python
    /usr/bin/python
    bash-4.3# which sed
    /bin/sed
  9. Exit from the bash shell of the container, stop it, and remove the container. To remove the container, perform the following steps:
    1. Find the container ID:
      docker ps -a \ > --format "table {{.ID}}\t{{.Image}}"
      CONTAINER id        IMAGE
      d8f3af5f7493        rtc-github-image-for-prereceive:latest
    2. Stop and remove the container.
      # docker container stop d8f3af5f7493 && \
      > docker rm d8f3af5f7493 
      d8f3af5f7493 
      d8f3af5f7493
  10. Run a container from the Docker image that you created previously.
    # docker create --name rtc-github-container-for-prereceive rtc-github-image-for-prereceive:latest /bin/bash
  11. Export the created container into a compressed tar-ball.
    # docker export rtc-github-container-for-prereceive | gzip > rtc-github-prereceive-hook.tar.gz

Create a pre-receive hook environment in GitHub Enterprise

About this task

There are two ways to upload the pre-receive hook environment to GitHub Enterprise. The following steps use the administrative shell to create the pre-receive hook environment.

Procedure

  1. Ensure that the access to the administrative shell via SSH is enabled in GitHub Enterprise. See Uploading a pre-receive hook environment via the admin center for details.
  2. Validate access to the GitHub Enterprise administrative shell:
    1. From the Linux workstation, run the following command:
      # ssh -p 122 admin@IP-address-of-the-GitHub-Enterprise-server
    2. If you are able to successfully log in, exit from the administrative shell: # exit
  3. Copy the pre-receive hook tar ball that you created previously to the GitHub Enterprise server by using the following command. Replace IP-address with the IP address of the GitHub Enterprise Server.
    # scp -P 122 ~/rtc-github-prereceive-hook.tar.gz admin@IP-address:/home/admin
  4. Connect to the administrative shell again, then run the following command to upload the pre-receive hook environment:
    # ghe-hook-env-create RTCGitHubPreReceiveEnv_7Sept2018 /home/admin/rtc-github-prereceive-hook.tar.gz

    When the command finishes, a message similar to the following is displayed: Pre-receive hook environment 'RTCGitHubPreReceiveEnv_7Sept2018' has been created.

Create a pre-receive hook repository

About this task

Use a Linux workstation to create the pre-receive hook repository.

Procedure

  1. Create a GitHub repository in the GitHub organization for hosting the pre-receive hook file. The code examples in this section use ScriptsRepo.git as the name of the repository.
  2. Clone the GitHub repository to your system:
    # git clone https://IP-address-of-GitHub-repo/GitHubOrgranization/ScriptsRepo.git
  3. Switch to the directory to which the repository was cloned:
    # cd ScriptsRepo.git
  4. Create a hooks folder.
    # mkdir hooks
  5. Copy the pre-receive hook file sample from ~/RTCImageForGitHub/server/hooks/examples/githubee/pre-receive.sh to the hooks folder:
    cp ~/RTCImageForGitHub/server/hooks/examples/githubee/pre-receive.sh hooks/rtc-pre-receive.sh
  6. Add executable permissions to the pre-receive hook script:
    # chmod ugo+x  hooks/rtc-pre-receive.sh
  7. Open the file hooks/rtc-pre-receive.sh and update the following variables:
    • GITHUB_URL: Specify the URL of the GitHub Enterprise server.
    • RTC_GIT_SERVER_TRACE_LEVEL: Set to 4. After you complete the setup, change this value to 1. Then commit and push the changes.

    Save the file.

  8. Run the following commands to push the changes to the remote GitHub repository:
    # git add hooks/rtc-pre-receive.sh
    # git status
    # git commit -m “add hook file”
    # git push

Create a pre-receive hook

Procedure

  1. Log in to the GitHub Enterprise web console as the site administrator.
  2. In the navigation pane of the Site Admin page, click Admin Center.
  3. In the navigation pane, click Hooks.
  4. On the Hooks page, click Add pre-receive hook.
  5. In the Hook name field, enter a name for the pre-receive hook.
  6. In the Environment section, select the pre-receive hook environment that you created previously.
  7. In the Script section, click Select hook repository and choose the GitHub repository that you created previously.
  8. Select the script file hooks/rtc-pre-receive.sh.
  9. Select the following enforcement options:
    • Use the exit-status to accept or reject pushes
    • Administrators can enable and disable this hook

    Disable the Enable this pre-receive hook on all repositories by default option while setting up the integration. Otherwise, process enforcement is applied on the pre-receive hooks repository, which is not registered in EWM.

  10. Click Add pre-receive hook to create the pre-receive hook.

video icon Video

Jazz.net channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community

Jazz.net
Jazz.net forums
Jazz.net library

support icon Support

IBM Support Community
Deployment wiki