pre-receiveフックスクリプトの作成

GitHub Enterprise Server の pre-receive フックの例は、github/platform-samplesリポジトリで見ることができます。

pre-receiveフックスクリプトの作成

A pre-receive hook script executes in a pre-receive hook environment on GitHub Enterprise Serverインスタンス. When you create a pre-receive hook script, consider the available input, output, exit status, and environment variables.

Input (stdin)

After a push occurs and before any refs are updated for the remote repository, the git-receive-pack process on GitHub Enterprise Serverインスタンス invokes the pre-receive hook script. Standard input for the script, stdin, is a string containing a line for each ref to update. Each line contains the old object name for the ref, the new object name for the ref, and the full name of the ref.

<old-value> SP <new-value> SP <ref-name> LF

This string represents the following arguments.

For more information about git-receive-pack, see "git-receive-pack" in the Git documentation. For more information about refs, see "Git References" in Pro Git.

Output (stdout)

The standard output for the script, stdout, is passed back to the client. Any echo statements will be visible to the user on the command line or in the user interface.

終了ステータス

The exit status of a pre-receive script determines if the push will be accepted.

環境変数

In addition to the standard input for your pre-receive hook script, stdin, GitHub Enterprise Server makes the following variables available in the Bash environment for your script's execution. For more information about stdin for your pre-receive hook script, see "Input (stdin)."

Different environment variables are available to your pre-receive hook script depending on what triggers the script to run.

• Always available
• Available for pushes from the web interface or API
• Available for pull request merges
• Available for pushes using SSH authentication

Always available

The following variables are always available in the pre-receive hook environment.

$GIT_DIR

$GIT_PUSH_OPTION_COUNT

$GIT_PUSH_OPTION_N

$GIT_USER_AGENT

$GITHUB_REPO_NAME

$GITHUB_REPO_PUBLIC

$GITHUB_USER_IP

$GITHUB_USER_LOGIN

Available for pushes from the web interface or API

The $GITHUB_VIA variable is available in the pre-receive hook environment when the ref update that triggers the hook occurs via either the web interface or the API for GitHub Enterprise Server. The value describes the action that updated the ref.

auto-merge deployment api

blob#save

branch merge api

branches page delete button

git refs create api

git refs delete api

git refs update api

git repo contents api

|

merge | Merge of a pull request using auto-merge | "Automatically merging a pull request" | |

merge base into head

pull request branch delete button

pull request branch undo button

pull request merge api

pull request merge button

pull request revert button

releases delete button

stafftools branch restore

tag create api

slumlord (#SHA)

web branch create

Available for pull request merges

The following variables are available in the pre-receive hook environment when the push that triggers the hook is a push due to the merge of a pull request.

$GITHUB_PULL_REQUEST_AUTHOR_LOGIN

$GITHUB_PULL_REQUEST_HEAD

$GITHUB_PULL_REQUEST_BASE

Available for pushes using SSH authentication

$GITHUB_PUBLIC_KEY_FINGERPRINT

権限の設定と GitHub Enterprise Server への pre-receive フックのプッシュ

A pre-receive hook script is contained in a repository on GitHub Enterprise Serverインスタンス. サイト管理者はリポジトリの権限を考慮し、適切なユーザ� けがアクセスできるようにしなければなりません。

フックは単一のリポジトリに集約することをおすすめします。 集約されたフックのリポジトリがパブリックになっている� �合、README.mdをポリシーの強制の説明に利用できます。 また、コントリビューションをプルリクエスト経由で受け付けることもできます。 しかし、pre-receiveフックはデフォルトブランチからのみ追� できます。 テストのワークフロー用には、設定を持つリポジトリのフォークを使うべきです。

1. Mac ユーザは、スクリプトに実行権限を持たせてく� さい。

   $ sudo chmod +x SCRIPT_FILE.sh

   Windows ユーザは、スクリプトに実行権限を持たせてく� さい。

   git update-index --chmod=+x SCRIPT_FILE.sh

2. Commit and push to the designated repository for pre-receive hooks on GitHub Enterprise Serverインスタンス.

   $ git commit -m "YOUR COMMIT MESSAGE"
   $ git push

3. Create the pre-receive hook on the GitHub Enterprise Server instance.

ローカルでのpre-receiveスクリプトのテスト

You can test a pre-receive hook script locally before you create or update it on GitHub Enterprise Serverインスタンス. その方法の 1 つは、pre-receive フックを実行できるリモートリポジトリとして働くローカルの Docker 環境を作成することです。

1. ローカルにDockerがインストールされていることを確認してく� さい。

2. 以下を含む Dockerfile.dev というファイルを作成してく� さい。

   FROM gliderlabs/alpine:3.3
   RUN \
     apk add --no-cache git openssh bash && \
     ssh-keygen -A && \
     sed -i "s/#AuthorizedKeysFile/AuthorizedKeysFile/g" /etc/ssh/sshd_config && \
     adduser git -D -G root -h /home/git -s /bin/bash && \
     passwd -d git && \
     su git -c "mkdir /home/git/.ssh && \
     ssh-keygen -t ed25519 -f /home/git/.ssh/id_ed25519 -P '' && \
     mv /home/git/.ssh/id_ed25519.pub /home/git/.ssh/authorized_keys && \
     mkdir /home/git/test.git && \
     git --bare init /home/git/test.git"
   
   VOLUME ["/home/git/.ssh", "/home/git/test.git/hooks"]
   WORKDIR /home/git
   
   CMD ["/usr/sbin/sshd", "-D"]
   

3. always_reject.sh というテストのpre-receiveスクリプトを作成してく� さい。 このスクリプト例では、全てのプッシュを拒否します。これは、リポジトリをロックする� �合に役立ちます。

   #!/usr/bin/env bash
   
   echo "error: rejecting all pushes"
   exit 1
   

4. always_reject.shスクリプトが実行権限を持つことを確認してく� さい。

   $ chmod +x always_reject.sh

5. Dockerfile.dev を含むディレクトリからイメージをビルドしてく� さい。

   $ docker build -f Dockerfile.dev -t pre-receive.dev .
   > Sending build context to Docker daemon 3.584 kB
   > Step 1 : FROM gliderlabs/alpine:3.3
   >  ---> 8944964f99f4
   > Step 2 : RUN apk add --no-cache git openssh bash && ssh-keygen -A && sed -i "s/#AuthorizedKeysFile/AuthorizedKeysFile/g"  /etc/ssh/sshd_config && adduser git -D -G root -h /home/git -s /bin/bash && passwd -d git && su git -c "mkdir /home/git/.ssh && ssh-keygen -t ed25519 -f /home/git/.ssh/id_ed25519 -P ' && mv /home/git/.ssh/id_ed25519.pub /home/git/.ssh/authorized_keys && mkdir /home/git/test.git && git --bare init /home/git/test.git"
   >  ---> Running in e9d79ab3b92c
   > fetch http://alpine.gliderlabs.com/alpine/v3.3/main/x86_64/APKINDEX.tar.gz
   > fetch http://alpine.gliderlabs.com/alpine/v3.3/community/x86_64/APKINDEX.tar.gz
   ....truncated output....
   > OK: 34 MiB in 26 packages
   > ssh-keygen: generating new host keys: RSA DSA ECDSA ED25519
   > Password for git changed by root
   > Generating public/private ed25519 key pair.
   > Your identification has been saved in /home/git/.ssh/id_ed25519.
   > Your public key has been saved in /home/git/.ssh/id_ed25519.pub.
   ....出力を省略....
   > Initialized empty Git repository in /home/git/test.git/
   > Successfully built dd8610c24f82

6. 生成された SSH キーを含むデータコンテナを実行してく� さい。

   $ docker run --name data pre-receive.dev /bin/true

7. テスト pre-receive フックの always_reject.sh をデータコンテナにコピーしてく� さい:

   $ docker cp always_reject.sh data:/home/git/test.git/hooks/pre-receive

8. sshd を実行しフックを動作させるアプリケーションコンテナを実行してく� さい。 返されたコンテナ ID をメモしておいてく� さい:

   $ docker run -d -p 52311:22 --volumes-from data pre-receive.dev
   > 7f888bc700b8d23405dbcaf039e6c71d486793cad7d8ae4dd184f4a47000bc58

9. 生成された SSH キーをデータコンテナからローカルマシンにコピーしてく� さい:

   $ docker cp data:/home/git/.ssh/id_ed25519 .

10. テストリポジトリのリモートを修正して、Docker コンテナ内の test.git リポジトリにプッシュしてく� さい。 この例では git@github.com:octocat/Hello-World.git を使用していますが、どのリポジトリを使用しても構いません。 この例ではローカルマシン (127.0.0.1) がポート 52311 をバインドしているものとしていますが、docker がリモートマシンで動作しているなら異なる IP アドレスを使うことができます。

    $ git clone git@github.com:octocat/Hello-World.git
    $ cd Hello-World
    $ git remote add test git@127.0.0.1:test.git
    $ GIT_SSH_COMMAND="ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 52311 -i ../id_ed25519" git push -u test main
    > Warning: Permanently added '[192.168.99.100]:52311' (ECDSA) to the list of known hosts.
    > Counting objects: 7, done.
    > Delta compression using up to 4 threads.
    > Compressing objects: 100% (3/3), done.
    > Writing objects: 100% (7/7), 700 bytes | 0 bytes/s, done.
    > Total 7 (delta 0), reused 7 (delta 0)
    > remote: error: rejecting all pushes
    > To git@192.168.99.100:test.git
    >  ! [remote rejected] main -> main (pre-receive hook declined)
    > error: failed to push some refs to 'git@192.168.99.100:test.git'

    pre-receive フックの実行後にプッシュが拒否され、スクリプトからの出力がエコーされていることに注意してく� さい。

参考リンク

• Pro Git Webサイトの「Gitのカスタマイズ - Gitポリシーの実施例」