サーバーフック

注:

  • サーバーフックは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になります。

リポジトリのサーバーフックを設定するには、以下の手順に従ってください：

  1. GitLab サーバー上のプロジェクトのパスを、管理エリア > Projectsに移動して探します。 そこから、フックを追加したいプロジェクトを選択します。 プロジェクトのリポジトリへのパスは、そのページの Gitaly 相対パスの下にあります。
  2. この場所にcustom_hooksという新しいディレクトリを作成します。
  3. 新しいcustom_hooks ディレクトリの内部に、フックの種類に合った名前のファイルを作成します。受信前フックの場合、ファイル名は拡張子なしのpre-receiveとします。
  4. フックファイルを実行可能にして、それがgitによって所有されていることを確認します。
  5. サーバーフックが期待通りに機能するようにコードを書いてください。 フックはどの言語でもかまいません。 先頭の’shebang’が言語の種類を適切に反映していることを確認してください。 例えば、スクリプトがRubyの場合、shebangはおそらく#!/usr/bin/env ruby。

フックコードが適切に実装されていれば、フックは適切に実行されます。

すべてのリポジトリに対してグローバルサーバフックを設定します。

インスタンス内のすべてのリポジトリに適用されるGitフックを作成するには、グローバルサーバーフックを設定します。 GitLabはグローバルフックをGitLab Shellhooks ディレクトリ内部で探すので、そこにフックを追加するとすべてのリポジトリに適用されます。 以下の手順に従って、すべてのリポジトリにサーバーフックを適切に設定してください：

  1. GitLabサーバー上で、設定されたカスタムフックディレクトリに移動します。デフォルトはGitLab Shellディレクトリです。ソースからのインストールの場合、GitLab Shellhook ディレクトリのパスは通常/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以降では尊重されます。
  2. この場所に新しいディレクトリを作成します。フックによって、pre-receive.d、post-receive.d、update.d のいずれかのディレクトリになります。
  3. この新しいディレクトリの中に、フックを追加します。 フックはどの言語でもかまいません。 一番上の「shebang」が言語の種類を適切に反映していることを確認してください。 たとえば、スクリプトがRubyの場合、shebangはおそらく#!/usr/bin/env rubyになるでしょう。
  4. フックファイルを実行可能にして、それがgitによって所有されていることを確認します。

フックが正しく機能しているか、テストしてください。

チェーンフック対応

GitLab Shell 4.1.0とGitLab 8.15で導入されました。

フックはグローバルにも、プロジェクト・ディレクトリごとに設定することもでき、フックの連鎖実行をサポートします。

注：<hook_name>.d は、pre-receive.d、post-receive.d、update.d のいずれかでないと正しく動作しません。その他の名前は無視されます。
注：.d ディレクトリのファイルは実行可能である必要があり、バックアップファイルのパターン（*~）と一致しない必要があります。

フックはこの順番で検索され、実行されます：

  1. GitLabサーバーフックを内蔵（ユーザーカスタマイズ不可）。
  2. <project>.git/custom_hooks/<hook_name> - プロジェクトごとのフック（これはすでに存在する動作として維持されました）。
  3. <project>.git/custom_hooks/<hook_name>.d/* - プロジェクトごとのフック。
  4. <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

Custom message from custom Git hook