{{< details >}}

  • Tier: 基础版,专业版,旗舰版
  • Offering: 私有化部署

{{< /details >}}

使用自定义文件钩子(不要与 服务器钩子系统钩子 混淆),可以在不修改极狐GitLab 源代码的情况下引入自定义集成。

文件钩子在每个事件上运行。你可以在文件钩子的代码中过滤事件或项目,并根据需要创建多个文件钩子。每个文件钩子在事件发生时由极狐GitLab 异步触发。有关事件列表,请参阅 系统钩子网络钩子 文档。

{{< alert type=”note” >}}

文件钩子必须在极狐GitLab 服务器的文件系统上配置。只有极狐GitLab 服务器管理员才能完成这些任务。如果你没有文件系统访问权限,可以考虑使用 系统钩子网络钩子 作为选项。

{{< /alert >}}

除了编写和支持自己的文件钩子之外,你还可以直接修改极狐GitLab 源代码并向上游贡献。通过这种方式,我们可以确保功能在各个版本中得到保留并通过测试覆盖。

设置自定义文件钩子

文件钩子必须在 file_hooks 目录中。子目录会被忽略。在 file_hooks 下的 example 目录 中查找示例。

要设置自定义钩子:

  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. 提供给文件钩子的数据在 STDIN 上以 JSON 格式提供。与 系统钩子 相同。

假设文件钩子代码已正确实现,钩子会按适当触发。文件钩子文件列表会根据每个事件进行更新。无需重启极狐GitLab 来应用新的文件钩子。

如果文件钩子执行时返回非零退出代码或极狐GitLab 执行失败,会记录消息到:

  • Linux 软件包安装中的 gitlab-rails/file_hook.log
  • 自编译安装中的 log/file_hook.log

文件钩子示例

此示例仅对事件 project_create 响应,极狐GitLab 实例通知管理员已创建新项目。

#!/opt/gitlab/embedded/bin/ruby
# 通过使用嵌入的 ruby 版本,我们消除了选择的语言可能不可用的可能性
require 'json'
require 'mail'

# 输入变量是 JSON 格式,因此我们需要先解析它。
ARGS = JSON.parse($stdin.read)

# 我们只想在事件 project_create 时触发此文件钩子
return unless ARGS['event_name'] == 'project_create'

# 我们将通知我们的 gitlab 实例的管理员创建了一个新项目
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 安装
sudo gitlab-rake file_hooks:validate

# 从源安装
cd /home/git/gitlab
bundle exec rake file_hooks:validate RAILS_ENV=production

输出示例:

从 /file_hooks 目录验证文件钩子
* /home/git/gitlab/file_hooks/save_to_file.clj 成功(零退出代码)
* /home/git/gitlab/file_hooks/save_to_file.rb 失败(非零退出代码)