ファイルフック

  • GitLab 10.6で導入されました。
  • GitLab 12.8まではPluginsという機能名でした。

カスタムファイルフックを使えば、GitLab管理者はGitLabのソースコードを変更することなく、カスタムインテグレーションを導入することができます。

注意: 自分のファイルフックを書いてサポートする代わりに、GitLabのソースコードに直接変更を加え、アップストリームに貢献することができます。 こうすることで、バージョン間で機能が維持され、テストによってカバーされることを保証することができます。
注：ファイルフックはGitLabサーバーのファイルシステム上で設定する必要があります。 GitLabサーバー管理者のみがこれらのタスクを完了することができます。 ファイルシステムにアクセスできない場合は、システムフックまたはwebhookをオプションとして検討してください。

ファイルフックは各イベントに対して実行されるので、ファイルフックコード内でイベントやプロジェクトをフィルタリングするのはあなた次第です。 ファイルフックはいくつでも持つことができます。 各ファイルフックは、イベントが発生するとGitLabによって非同期にトリガーされます。 イベントのリストについては、システムフックのドキュメントを参照してください。

セットアップ

ファイルフックはfile_hooks ディレクトリに直接置く必要があります。サブディレクトリは無視されます。file_hooks](https://gitlab.com/gitlab-org/gitlab/tree/master/file_hooks/examples)の内部には[example ディレクトリがあり、基本的なサンプルを見ることができます。

カスタムフックを設定するには、以下の手順に従ってください：

  1. GitLab サーバー上で、プラグインディレクトリに移動します。 ソースからのインストールの場合、パスは通常/home/git/gitlab/file_hooks/です。 Omnibus のインストールの場合、パスは通常/opt/gitlab/embedded/service/gitlab-rails/file_hooksです。

    複数のサーバーを使用する構成の場合、フック・ファイルは各アプリケーション・サーバー上に存在する必要があります。

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

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

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

  • gitlab-rails/plugin.log オムニバスのインストールで
  • log/plugin.log をインストールする必要があります。

ファイルフックの作成

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

# By using the embedded ruby version we eliminate the possibility that our chosen language
# would be unavailable from
#!/opt/gitlab/embedded/bin/ruby
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)