ファイルフック

カスタムファイルフック（サーバーフックや システムフックと混同しないでください）を使って、GitLabのソースコードを変更することなくカスタムインテグレーションを導入することができます。

ファイルフックはイベントごとに実行されます。ファイルフックのコードでイベントやプロジェクトをフィルタリングし、必要な数のファイルフックを作成することができます。各ファイルフックはイベント発生時にGitLabによって非同期にトリガーされます。イベントの一覧はシステムフックのドキュメントを参照してください。

note
ファイルフックはGitLabサーバーのファイルシステムに設定する必要があります。GitLabサーバー管理者のみがこれらの作業を行うことができます。ファイルシステムにアクセスできない場合は、システムフックや Webhookをオプションとして検討してください。

自分でファイルフックを書いてサポートする代わりに、GitLabのソースコードに直接変更を加え、アップストリームに貢献することもできます。こうすることで、バージョン間で機能が維持され、テストによってカバーされることを保証することができます。

カスタムファイルフックのセットアップ

ファイルフックはfile_hooks ディレクトリになければなりません。サブディレクトリは無視されます。サンプルはexample ディレクトリのfile_hooksの下にあります。

カスタムフックを設定するには

  1. GitLab サーバー上でプラグインディレクトリを探します。セルフコンパイルインストールの場合、パスは通常/home/git/gitlab/file_hooks/ です。Linux パッケージインストールの場合、パスは通常/opt/gitlab/embedded/service/gitlab-rails/file_hooksです。

    複数のサーバーがある設定の場合、フックファイルはそれぞれのアプリケーションサーバーに存在する必要があります。

  2. file_hooks ディレクトリ内部に、スペースや特殊文字を含まない任意の名前のファイルを作成します。
  3. フックファイルを実行可能にして、Gitユーザーがそのファイルを所有するようにしてください。
  4. フックファイルを期待通りに機能させるためのコードを書きます。どの言語でもかまいません。そして、先頭にある ‘shebang’ が言語の種類を適切に反映するようにしましょう。例えば、スクリプトが Ruby である場合、shebang はおそらく#!/usr/bin/env ruby.
  5. ファイルフックへのデータはJSONとしてSTDIN で提供されます。これはシステムフックとまったく同じです。

ファイルフックのコードが適切に実装されていれば、フックは適切なタイミングで起動します。ファイルフックのファイルリストはイベントごとに更新されます。新しいファイルフックを適用するためにGitLabを再起動する必要はありません。

ファイルフックがゼロ以外の終了コードで実行されるか、GitLabが実行に失敗すると、メッセージがログに記録されます：

  • gitlab-rails/file_hook.log Linuxパッケージのインストールの場合。
  • log/file_hook.log セルフコンパイルインストールの場合。

ファイルフックの例

この例ではイベントproject_create に対してのみ応答し、GitLab インスタンスは新しいプロジェクトが作成されたことを管理者に通知します。

#!/opt/gitlab/embedded/bin/ruby
# By using the embedded ruby version we eliminate the possibility that our chosen language
# would be unavailable from
require 'json'
require 'mail'

# The incoming variables are in JSON format so we need to parse it first.
ARGS = JSON.parse($stdin.read)

# We only want to trigger this file hook on the event project_create
return unless ARGS['event_name'] == 'project_create'

# We will inform our admins of our gitlab instance that a new project is created
Mail.deliver do
  from    'info@gitlab_instance.com'
  to      'admin@gitlab_instance.com'
  subject "new project " + ARGS['name']
  body    ARGS['owner_name'] + 'created project ' + ARGS['name']
end

検証の例

独自のファイルフックを書くのは厄介で、システムを変更せずにチェックできれば簡単です。Rakeタスクが提供されているので、ステージング環境で使用して、本番環境で使用する前にファイルフックをテストすることができます。Rakeタスクはサンプルデータを使い、各ファイルフックを実行します。出力は、システムがあなたのファイルフックを見ているかどうか、エラーなしで実行されたかどうかを判断するのに十分なものでなければなりません。

# Omnibus installations
sudo gitlab-rake file_hooks:validate

# Installations from source
cd /home/git/gitlab
bundle exec rake file_hooks:validate RAILS_ENV=production

出力の例：

Validating file hooks from /file_hooks directory
* /home/git/gitlab/file_hooks/save_to_file.clj succeed (zero exit code)
* /home/git/gitlab/file_hooks/save_to_file.rb failure (non-zero exit code)