サーバーフック
注:
- サーバーフックはGitLab 12.8でカスタムフックに代わって導入されました。
- サーバーフックはGitLabサーバーのファイルシステム上で設定する必要があります。 GitLabサーバー管理者のみがこれらの作業を行うことができます。 ファイルシステムにアクセスできない場合は、webhookや GitLab CI/CDを選択肢として検討してください。 ユーザーが設定可能なGitフックインターフェイスについては、GitLab Starterで利用可能なPush Rulesを参照してください。 .
- GitLabGeoを使用している場合、サーバーフックはセカンダリノードにレプリケートされません。
git は、さまざまなアクションに対して実行されるフックをネイティブにサポートしています。 これらのフックはサーバー上で実行され、特定のコミットポリシーを強制したり、リポジトリの状態に基づいてその他のタスクを実行したりするために使うことができます。
サーバーサイド Git フックの例としては、pre-receive
、post-receive
、update
などがあります。各フックの詳細についてはGit SCM Server-Side Hooksを参照ください。
リポジトリ用サーバーフックの作成
サーバーサイドのGitフックは、通常リポジトリのhooks
サブディレクトリhooks
に置かれますhooks
。 GitLabでは、フックディレクトリはGitLab Shellhooks
ディレクトリhooks
にシンボリックリンクされてhooks
おり、GitLab Shellのアップグレード時のメンテナンスが容易になっています。 サーバーフックの実装は異なりますが、フックが作成された後の動作はまったく同じです。
/home/git/repositories/<group>/<project>.git
になります。Omnibus のインストールの場合、パスは通常/var/opt/gitlab/git-data/repositories/<group>/<project>.git
になります。リポジトリのサーバーフックを設定するには、以下の手順に従ってください:
- GitLab サーバー上のプロジェクトのパスを、管理エリア > Projectsに移動して探します。 そこから、フックを追加したいプロジェクトを選択します。 プロジェクトのリポジトリへのパスは、そのページの Gitaly 相対パスの下にあります。
- この場所に
custom_hooks
という新しいディレクトリを作成します。 - 新しい
custom_hooks
ディレクトリの内部に、フックの種類に合った名前のファイルを作成します。受信前フックの場合、ファイル名は拡張子なしのpre-receive
とします。 - フックファイルを実行可能にして、それがgitによって所有されていることを確認します。
- サーバーフックが期待通りに機能するようにコードを書いてください。 フックはどの言語でもかまいません。 先頭の’shebang’が言語の種類を適切に反映していることを確認してください。 例えば、スクリプトがRubyの場合、shebangはおそらく
#!/usr/bin/env ruby
。
フックコードが適切に実装されていれば、フックは適切に実行されます。
すべてのリポジトリに対してグローバルサーバフックを設定します。
インスタンス内のすべてのリポジトリに適用されるGitフックを作成するには、グローバルサーバーフックを設定します。 GitLabはグローバルフックをGitLab Shellhooks
ディレクトリ内部で探すので、そこにフックを追加するとすべてのリポジトリに適用されます。 以下の手順に従って、すべてのリポジトリにサーバーフックを適切に設定してください:
-
GitLabサーバー上で、設定されたカスタムフックディレクトリに移動します。デフォルトはGitLab Shellディレクトリです。ソースからのインストールの場合、GitLab Shell
hook
ディレクトリのパスは通常/home/git/gitlab-shell/hooks
です。Omnibusインストールの場合、パスは通常/opt/gitlab/embedded/service/gitlab-shell/hooks
です。グローバルカスタムフックを別のディレクトリで探すには、Gitaly configでcustom_hooks_dir
を設定します。Omnibusインストールの場合、これはgitlab.rb
に設定されます。ソースインストールの場合、設定場所はGitLabバージョンに依存します:- GitLab 13.0以前では、
gitlab-shell/config.yml
で設定します。 - GitLab 13.1 以降では、
gitaly/config.toml
の[hooks]
セクションで設定します。
注:gitlab-shell/config.yml
のcustom_hooks_dir
の値は、gitaly/config.toml
の値が空白か存在しない場合でも、GitLab 13.1以降では尊重されます。 - GitLab 13.0以前では、
- この場所に新しいディレクトリを作成します。フックによって、
pre-receive.d
、post-receive.d
、update.d
のいずれかのディレクトリになります。 - この新しいディレクトリの中に、フックを追加します。 フックはどの言語でもかまいません。 一番上の「shebang」が言語の種類を適切に反映していることを確認してください。 たとえば、スクリプトがRubyの場合、shebangはおそらく
#!/usr/bin/env ruby
になるでしょう。 - フックファイルを実行可能にして、それがgitによって所有されていることを確認します。
フックが正しく機能しているか、テストしてください。
チェーンフック対応
GitLab Shell 4.1.0とGitLab 8.15で導入されました。
フックはグローバルにも、プロジェクト・ディレクトリごとに設定することもでき、フックの連鎖実行をサポートします。
<hook_name>.d
は、pre-receive.d
、post-receive.d
、update.d
のいずれかでないと正しく動作しません。その他の名前は無視されます。.d
ディレクトリのファイルは実行可能である必要があり、バックアップファイルのパターン(*~
)と一致しない必要があります。フックはこの順番で検索され、実行されます:
- GitLabサーバーフックを内蔵(ユーザーカスタマイズ不可)。
-
<project>.git/custom_hooks/<hook_name>
- プロジェクトごとのフック(これはすでに存在する動作として維持されました)。 -
<project>.git/custom_hooks/<hook_name>.d/*
- プロジェクトごとのフック。 -
<custom_hooks_dir>/<hook_name>.d/*
- グローバルフック:すべての実行可能ファイル(エディタのバックアップファイルを除く)。
同じタイプのフックは順番に実行され、最初のスクリプトがゼロ以外の値で終了すると、実行は停止します。
<project>.git
では、プロジェクト名を GitLab が使うハッシュストレージ形式に変換する必要があります。
カスタムエラーメッセージ
GitLab 8.10 で導入されました。
コミットが拒否されたり、Gitフック中にエラーが発生したときにGitLabのUIにカスタムエラーメッセージを表示させるには、スクリプトが必要です:
- カスタムエラーメッセージをスクリプトの
stdout
またはstderr
に送信します。 - 各メッセージのプレフィックスは、
GL-HOOK-ERR:
で、プレフィックスの前には文字を入れません。
カスタムエラーメッセージの例
Bashで書かれたこのフックスクリプトは、GitLabのUIに次のようなメッセージを表示します:
#!/bin/sh
echo "GL-HOOK-ERR: My custom error message.";
exit 1