{{< details >}}
- Tier: 基础版，专业版，旗舰版
- Offering: 私有化部署
{{< /details >}}
使用自定义文件钩子（不要与 服务器钩子 或 系统钩子 混淆），可以在不修改极狐GitLab 源代码的情况下引入自定义集成。
文件钩子在每个事件上运行。你可以在文件钩子的代码中过滤事件或项目，并根据需要创建多个文件钩子。每个文件钩子在事件发生时由极狐GitLab 异步触发。有关事件列表，请参阅 系统钩子 和 网络钩子 文档。
{{< alert type=”note” >}}
文件钩子必须在极狐GitLab 服务器的文件系统上配置。只有极狐GitLab 服务器管理员才能完成这些任务。如果你没有文件系统访问权限，可以考虑使用 系统钩子 或 网络钩子 作为选项。
{{< /alert >}}
除了编写和支持自己的文件钩子之外，你还可以直接修改极狐GitLab 源代码并向上游贡献。通过这种方式，我们可以确保功能在各个版本中得到保留并通过测试覆盖。
设置自定义文件钩子
文件钩子必须在 file_hooks 目录中。子目录会被忽略。在 file_hooks 下的 example 目录 中查找示例。
要设置自定义钩子：
-
在极狐GitLab 服务器上，找到插件目录。对于自编译安装，路径通常是
/home/git/gitlab/file_hooks/。对于 Linux 软件包安装，路径通常是/opt/gitlab/embedded/service/gitlab-rails/file_hooks。对于 配置多个服务器，你的钩子文件应该存在于每个应用服务器上。
- 在
file_hooks目录中，创建一个你选择的名称的文件，不要包含空格或特殊字符。 - 使钩子文件可执行并确保它由 Git 用户拥有。
- 编写代码以使文件钩子按预期功能运行。代码可以是任何语言，并确保顶部的 ‘shebang’ 正确反映语言类型。例如，如果脚本是 Ruby，则 shebang 可能是
#!/usr/bin/env ruby。 - 提供给文件钩子的数据在
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 失败（非零退出代码）