ファイルフック

カスタムファイルフックを使用して、GitLabソースコードを修正せずに、カスタムインテグレーションを導入します。

ファイルフックは各エントリで実行されます。ファイルフックのコードでエントリまたはプロジェクトをフィルタリングし、必要に応じて多数のファイルフックを作成できます。各ファイルフックは、エントリの場合、GitLabによって非同期的にトリガーされます。エントリのリストについては、システムフックとWebhookのドキュメントを参照してください。

独自のファイルフックを作成してサポートする代わりに、GitLabソースコードを直接変更して、アップストリームにコントリビュートすることもできます。このようにして、機能がバージョン間で維持され、テストでカバーされるようにすることができます。

カスタムファイルフックをセットアップする

ファイルフックは、file_hooksディレクトリにある必要があります。サブディレクトリは無視されます。file_hooks下のexampleディレクトリに例があります。

カスタムフックをセットアップするには:

1. Sidekiqコンポーネントを実行しているGitLabサーバーで、プラグインディレクトリを見つけます。自己コンパイルによるインストールの場合、パスは通常/home/git/gitlab/file_hooks/です。Linuxパッケージインストールの場合、パスは通常/opt/gitlab/embedded/service/gitlab-rails/file_hooksです。

   複数のサーバーでの設定の場合、フックファイルは各Sidekiqサーバーに存在する必要があります。

2. file_hooksディレクトリ内で、スペースや特殊文字を含まない、任意の名前のファイルを作成します。

3. フックファイルを実行可能にし、Gitユーザーが所有していることを確認します。

4. 期待どおりにファイルフックが機能するようにコードを記述します。これは任意の言語で記述でき、上部の「シバン」が言語タイプを適切に反映していることを確認します。たとえば、スクリプトがRubyで記述されている場合、シバンはおそらく#!/usr/bin/env rubyとなります。

5. ファイルフックへのデータは、STDINのJSONとして提供されます。これはシステムフックとまったく同じです。

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

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

• 自己コンパイルによるインストールの場合: log/file_hook.log。
• Linuxパッケージインストールの場合: gitlab-rails/file_hook.log。

このファイルは、ファイルフックがゼロ以外の状態で終了した場合にのみ作成されます。ファイルフックが実行されると、開始された各FileHookWorkerのSidekiqログgitlab/sidekiq/currentにエントリが追加されます。このエントリには、エントリの詳細と、実行されたスクリプトが含まれています。

ファイルフックの例

この例は、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)

関連トピック

• サーバーフック
• システムフック