如何在GitLab中激活pre-receive钩子？自定义钩子配置后未生效如何排查？

路径放置错误（最常见根因） #

• 你当前创建pre-receive钩子的位置是本地代码克隆目录下的.git/custom_hooks，这个路径的文件永远不会被GitLab服务器端执行。GitLab的服务钩子是挂载在服务器端存储的bare裸仓库下的，和你本地拉取代码生成的.git目录完全是两个独立的存储位置，本地目录下的钩子配置不会同步到服务器。
• 服务器端对应裸仓库的真实路径可以通过以下命令在GitLab服务器上查询：
  sudo gitlab-rails runner -e production 'puts Gitlab::GitalyClient::StorageSettings.allow_disk_access { Project.find_by_full_path("你的命名空间/仓库名").repository.path_to_repo }'
  得到的路径类似/var/opt/gitlab/git-data/repositories/你的组名/你的仓库名.git，你需要在这个服务器端路径下创建custom_hooks子目录，放入pre-receive脚本，才会被GitLab识别。

权限配置不符合安全规则 #

• 即便把脚本放到了正确的服务器端裸仓库路径下，权限不匹配也会被Gitaly进程直接跳过执行：
  • 从裸仓库根目录、custom_hooks子目录到pre-receive文件本身的所有路径层级，属主必须是git:git。你之前展示的文件属主为git、属组为root，属组不匹配会触发Gitaly的安全拦截，直接跳过钩子加载。
  • 不要使用全局可写的777权限配置：按GitLab的安全要求，custom_hooks目录权限设置为700，内部钩子文件权限设置为755。全局可写的权限会被Gitaly判定为不安全，拒绝执行。
  • 如果脚本是在Windows环境下编辑生成的，需要执行dos2unix pre-receive将文件转成Unix换行格式，否则脚本会因为格式错误无法正常加载。

触发时机的认知偏差 #

• pre-receive钩子的触发前提是推送请求包含实际的引用更新：如果推送的内容没有任何新增commit变更，钩子本来就不会被触发。
• 修正路径和权限配置后，不需要重启GitLab服务，直接推送代码即可测试。如果仍不触发，可以查看Gitaly日志/var/log/gitlab/gitaly/current，里面会记录钩子加载、执行失败的具体原因。
• 你用于测试的脚本内容（#!/bin/sh + exit 1）逻辑本身没有问题，只要钩子被正常加载执行，就会拦截所有推送请求。

内容的提问来源于stack exchange，提问作者Stefan