Git 服务器钩子

从服务器钩子更名为 Git 服务器钩子于 15.6 版本。

Git 服务器钩子在极狐GitLab 服务器上运行自定义逻辑。您可以使用它们来运行与 Git 相关的任务,例如:

  • 执行特定的提交策略。
  • 根据仓库的状态执行任务。

Git 服务器钩子使用 pre-receivepost-receiveupdate Git 服务器端钩子

极狐GitLab 管理员在极狐GitLab 服务器的文件系统上配置服务器钩子。如果您没有文件系统访问权限,服务器钩子的替代方案包括:

Geo 不会将服务器钩子复制到次要节点。

为仓库创建服务器钩子

要为仓库创建服务器钩子:

  1. 在顶部栏上,选择 主菜单 > 管理员
  2. 转到 概览 > 项目 并选择要添加服务器钩子的项目。
  3. 在出现的页面,找到 Gitaly 相对路径 的值。此路径是服务器钩子必须位于的位置。
    • 如果您使用哈希存储,请参阅转换哈希存储路径,了解有关解释相对路径的信息。
    • 如果您不使用哈希存储
      • 对于 Omnibus GitLab 安装实例,路径通常是 /var/opt/gitlab/git-data/repositories/<group>/<project>.git
      • 对于源安装实例,路径通常是 /home/git/repositories/<group>/<project>.git
  4. 在文件系统上,在正确的位置创建一个名为 custom_hooks 的新目录。
  5. 在新的 custom_hooks 目录中:
    • 要创建单个服务器钩子,请创建一个名称与钩子类型匹配的文件。例如,对于 pre-receive 服务器钩子,文件名应该是 pre-receive 并且没有扩展名。
    • 要创建许多服务器钩子,请为与钩子类型匹配的钩子创建一个目录。例如,对于 pre-receive 服务器钩子,目录名称应该是 pre-receive.d。将钩子的文件放在该目录中。
  6. 使服务器钩子文件可执行并确保它们归 Git 用户所有。
  7. 编写代码使服务器钩子功能如预期。Git 服务器钩子可以使用任何编程语言。确保顶部的 shebang 反映语言类型。例如,脚本在 Ruby 中,则 shebang 可能是 #!/usr/bin/env ruby
  8. 使钩子文件可执行,确保它由 Git 用户拥有,并确保它与备份文件模板 (*~) 不匹配。

如果服务器钩子代码被正确实现,它应该在下次触发 Git 钩子时执行。

为所有仓库创建全局服务器钩子

要创建适用于所有存储库的 Git 钩子,请设置全局服务器钩子。全局服务器钩子也适用于:

  • 项目和群组 wiki 仓库。它们的存储目录名称采用 <id>.wiki.git 格式。
  • 设计管理项目下的仓库。它们的存储目录名称采用 <id>.design.git 格式。

选择服务器钩子目录

在创建全局服务器钩子之前,您必须为其选择一个目录。

对于 Omnibus 安装实例,该目录在 gitaly['custom_hooks_dir'] 下的 gitlab.rb 中设置。您可以:

  • 通过取消注释,使用 /var/opt/gitlab/gitaly/custom_hooks 目录的默认建议。
  • 添加您自己的设置。

对于源安装实例:

  • 该目录在配置文件中设置。配置文件的位置取决于极狐GitLab 版本:
    • 对于 13.1 及更高版本,目录在 [hooks] 部分下的 gitaly/config.toml 中设置。但是,如果 gitlab-shell/config.yml 中的值是空白或不存在,极狐GitLab 会优先使用 gitlab-shell/config.yml 中的 custom_hooks_dir 值。
    • 对于 13.0 及更早版本,目录在 gitlab-shell/config.yml 中设置。
  • 默认目录是 /home/git/gitlab-shell/hooks

创建全局服务器钩子

为所有仓库创建全局服务器钩子:

  1. 在极狐GitLab 服务器上,进入配置的全局服务器钩子目录。
  2. 在配置的全局服务器钩子目录中,为匹配钩子类型的钩子创建一个目录。例如,对于 pre-receive 服务器钩子,目录名称应为 pre-receive.d
  3. 在这个新目录中,添加您的服务器钩子。Git 服务器钩子可以使用任何编程语言。确保顶部的 shebang 反映语言类型。例如,脚本在 Ruby 中,则 shebang 可能是 #!/usr/bin/env ruby
  4. 使钩子文件可执行,确保它由 Git 用户拥有,并确保它与备份文件模板 (*~) 不匹配。

如果服务器钩子代码被正确实现,它应该在下次触发 Git 钩子时执行。钩子按钩子类型子目录中文件名的字母顺序执行。

链式服务器钩子

极狐GitLab 可以在链式执行服务器钩子。极狐GitLab 按以下顺序搜索并执行服务器钩子:

  • 内置极狐GitLab 服务器钩子。用户无法自定义这些服务器钩子。
  • <project>.git/custom_hooks/<hook_name>:每个项目的钩子。保留此位置是为了向后兼容。
  • <project>.git/custom_hooks/<hook_name>.d/*:每个项目钩子的位置。
  • <custom_hooks_dir>/<hook_name>.d/*:所有可执行全局钩子文件的位置,除了编辑器备份文件。

在服务器钩子目录中:

  • 钩子按字母顺序执行。
  • 当钩子以非零值退出时停止执行。

服务器钩子可用的环境变量

您可以将任何环境变量传递给服务器钩子,但您应该只依赖受支持的环境变量。

所有服务器钩子都支持以下极狐GitLab 环境变量:

环境变量 描述
GL_ID 发起推送的用户的极狐GitLab 标识符。例如,user-2234
GL_PROJECT_PATH (13.2 及更高版本)极狐GitLab 项目路径。
GL_PROTOCOL (13.2 及更高版本)用于此更改的协议。以下之一:http(使用 HTTP 的 Git push)、ssh(使用 SSH 的 Git push)或 web(所有其他操作)。
GL_REPOSITORY project-<id> 其中 id 是项目的 ID。
GL_USERNAME 发起推送的用户的极狐GitLab 用户名。

pre-receivepost-receive 服务器钩子支持以下 Git 环境变量:

环境变量 描述
GIT_ALTERNATE_OBJECT_DIRECTORIES 隔离环境中的备用对象目录。请参阅 Git receive-pack 文档
GIT_OBJECT_DIRECTORY 隔离环境中的极狐GitLab 项目路径。 请参阅 Git receive-pack 文档
GIT_PUSH_OPTION_COUNT 推送选项的数量。请参阅 Git pre-receive 文档
GIT_PUSH_OPTION_<i> 推送选项的值,其中 i0GIT_PUSH_OPTION_COUNT - 1。请参阅 Git pre-receive 文档

自定义错误消息

当提交被拒绝或 Git hook 期间发生错误时,您可以在 UI 中显示自定义错误消息。要显示自定义错误消息,您的脚本必须:

  • 将自定义错误消息发送到脚本的 stdoutstderr
  • 使用 GL-HOOK-ERR: 为每条消息添加前缀,前缀之前不出现任何字符。

例如:

#!/bin/sh
echo "GL-HOOK-ERR: My custom error message.";
exit 1