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 the RTCImageForGitHub folder. Replace full-path-to-downloaded-EWM-Git-server-toolkit-zip-file with the full-path-to-the-EWM-Git-server-toolkit-zip-file. For example: unzip -d ~/RTCImageForGitHub /Downloads/Git-Server-Toolkit-6.0.6.zip
  4. Create a text file named token.txtand add the personal access token that you created in the previous section into that file. Run the following commands one after the other. If the personal access token string is 8b5596aa832dbf065800bf69bbc3ac1e715ab39d, then replace generated-personal-access-token in the command with 8b5596aa832dbf065800bf69bbc3ac1e715ab39d. You can also add comments to the file to make it more informational. Comment lines start with #.The first line that does not begin with # is considered as the personal access token. For example:
    touch ~/RTCImageForGitHub/token.txt 
    echo generated-personal-access-token > ~/RTCImageForGitHub/token.txt 
    echo  "#token generated on date for user" >> ~/RTCImageForGitHub/token.txt
  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 
    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
  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.
    1. Run which bash. The output will be similar to this:
      /bin/bash
      .
    2. Run the following commands one after the other:
      which make
      which git
      which node
      which sed

      The output should be similar to the following:

      /usr/bin/make
      /usr/bin/git
      /usr/bin/node
      /bin/sed
  9. Exit from the bash shell of the container, stop it, and remove the container.
    1. To exit from the bash shell of the container, click Ctrl/D, or enter exit.
    2. Return to the command shell prompt of your host system.
    3. Find the container ID by entering the following command:
      docker ps -a --format "table {{.ID}}\t{{.Image}}"
      The output looks similar to the following:
      CONTAINER ID        IMAGE
                d8f3af5f7493        rtc-github-image-for-prereceive:latest
    4. Stop and remove the container by entering the following command.
      docker stop container-ID && docker rm container-ID
  10. Run a container from the Docker image that you created previously.
    1. Remove any container with the name rtc-github-container-for-prereceive before you run the following command:
      docker rm rtc-github-container-for-prereceive
      docker create --name rtc-github-container-for-prereceive rtc-github-image-for-prereceive:latest /bin/bash
    2. Create the container using the following command:
      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 using the ssh command (see step 1), then run the following command to upload the pre-receive hook environment:
    ghe-hook-env-create RTCGitHubPreReceiveEnv_current-date /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_10Sept2019' 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