Help us learn about your current experience with the documentation. Take the survey.

文件钩子

  • 版本：Free, Premium, Ultimate
  • 产品：GitLab Self-Managed

使用自定义文件钩子（不要与服务器钩子或系统钩子混淆），在不修改 GitLab 源代码的情况下引入自定义集成。

文件钩子会在每个事件上运行。您可以在文件钩子的代码中过滤事件或项目，并根据需要创建任意数量的文件钩子。当事件发生时，每个文件钩子都会由 GitLab 异步触发。有关事件列表，请参阅系统钩子和Web 钩子文档。

文件钩子必须在 GitLab 服务器的文件系统上进行配置。只有 GitLab 服务器管理员才能完成这些任务。如果您没有文件系统访问权限，请考虑探索系统钩子或Web 钩子作为替代方案。

除了编写和维护您自己的文件钩子，您也可以直接修改 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. 编写代码以使文件钩子按预期工作。代码可以使用任何语言，并确保顶部的 ‘shebang’ 正确反映语言类型。例如，如果脚本使用 Ruby 编写，shebang 可能是 #!/usr/bin/env ruby。

  5. 传递给文件钩子的数据以 JSON 格式通过 STDIN 提供。这与系统钩子的数据格式完全相同。

假设文件钩子代码已正确实现，钩子会在适当时机触发。文件钩子列表会在每个事件发生时更新。应用新的文件钩子无需重启 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)