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

Git 服务器钩子

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed

Git 服务器钩子（不要与 系统钩子 或 文件钩子 混淆）在 GitLab 服务器上运行自定义逻辑。您可以使用它们来运行与 Git 相关的任务，例如：

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

Git 服务器钩子使用 pre-receive、post-receive 和 update Git 服务器端钩子。

GitLab 管理员使用 gitaly 命令配置服务器钩子，该命令还：

  • 用于启动 Gitaly 服务器。
  • 提供多个子命令。
  • 连接到 Gitaly gRPC API。

如果您无法访问 gitaly 命令，服务器钩子的替代方案包括：

Geo 不会将服务器钩子复制到辅助节点。

为仓库设置服务器钩子

Prerequisites:

  • The storage name, path to the Gitaly configuration file (default is /var/opt/gitlab/gitaly/config.toml on Linux package instances), and the repository relative path for the repository.
  • Any language runtimes and utilities that are required by the hooks must be installed on each of the servers that run Gitaly.

To set server hooks for a repository:

  1. Create tarball containing custom hooks:

    1. 编写代码以使服务器钩子按预期运行。Git 服务器钩子可以使用任何编程语言。 确保 shebang 顶部反映语言类型。例如， 如果脚本使用 Ruby 编写，shebang 可能是 #!/usr/bin/env ruby。

      • 要创建单个服务器钩子，请创建一个与钩子类型匹配的文件名。例如，对于 pre-receive 服务器钩子，文件名应该是 pre-receive，没有扩展名。
      • 要创建多个服务器钩子，请为钩子创建一个与钩子类型匹配的目录。例如，对于 pre-receive 服务器钩子，目录名称应该是 pre-receive.d。将钩子的文件放在该目录中。

    2. 确保服务器钩子文件是可执行的，并且不匹配备份文件模式（*~）。服务器钩子应该 位于 tarball 根目录的 custom_hooks 目录中。

    3. 使用 tar 命令创建自定义钩子存档。例如，tar -cf custom_hooks.tar custom_hooks。

  2. 使用必需选项运行 hooks set 子命令，为仓库设置 Git 钩子。例如， cat custom_hooks.tar | sudo -u git -- /opt/gitlab/embedded/bin/gitaly hooks set --storage <storage> --repository <relative path> --config <config path>。

    • 需要提供节点有效 Gitaly 配置的路径以连接到节点，并将其提供给 --config 标志。
    • 自定义钩子 tarball 必须通过 stdin 传递。例如，cat custom_hooks.tar | sudo -u git -- /opt/gitlab/embedded/bin/gitaly hooks set --storage <storage> --repository <relative path> --config <config path>。

  3. 如果您使用 Gitaly Cluster (Praefect)，则必须在所有 Gitaly 节点上运行 hooks set 子命令。更多信息，请参阅 Gitaly Cluster (Praefect) 上的服务器钩子。

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

To create server hooks for a repository:

  1. 在左侧边栏底部，选择 管理员。
  2. 转到 概览 > 项目 并选择要添加服务器钩子的项目。
  3. 在出现的页面上，找到 相对路径 的值。此路径是服务器钩子必须位于的位置。
    • 如果您使用 哈希存储，请参阅 转换哈希存储路径 了解有关 解释相对路径的信息。
    • 如果您不使用 哈希存储：
      • 对于 Linux 包安装，路径通常是 /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. 确保钩子文件不匹配备份文件模式（*~）。
  9. 如果您使用 Gitaly Cluster (Praefect)，则必须在所有 Gitaly 节点上重复此过程。更多信息，请参阅 Gitaly Cluster (Praefect) 上的服务器钩子。

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

Gitaly Cluster (Praefect) 上的服务器钩子

如果您使用 Gitaly Cluster (Praefect)，单个仓库可能会被复制到 Praefect 中的多个 Gitaly 存储。 因此，钩子脚本必须复制到拥有仓库副本的每个 Gitaly 节点。 为此，请按照为适用版本设置自定义仓库钩子的相同步骤操作，并为每个存储重复此操作。

复制脚本的路径取决于仓库的存储位置。新仓库使用 Praefect 生成的副本路径， 这不是哈希存储路径。可以通过 查询 Praefect 仓库元数据 使用 -relative-path 指定期望的 GitLab 哈希存储路径来识别副本路径。

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

要创建适用于所有仓库的 Git 钩子，请设置全局服务器钩子。全局服务器钩子也适用于：

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

选择服务器钩子目录

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

对于 Linux 包安装，目录在 gitlab.rb 中的 gitaly['configuration'][:hooks][:custom_hooks_dir] 下设置。您可以：

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

对于自编译安装：

  • 目录在 gitaly/config.toml 中的 [hooks] 部分下设置。但是， 如果 gitaly/config.toml 中的值为空或不存在，GitLab 会遵循 gitlab-shell/config.yml 中的 custom_hooks_dir 值。
  • 默认目录是 /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 钩子下次触发时执行。钩子在钩子类型子目录中按文件名字母顺序执行。

移除仓库的服务器钩子

Prerequisites:

To remove server hooks, pass an empty tarball to hook set to indicate that the repository should contain no hooks. For example:

cat empty_hooks.tar | sudo -u git -- /opt/gitlab/embedded/bin/gitaly hooks set --storage <storage> --repository <relative path> --config <config path>

To remove server hooks:

  1. 转到仓库在磁盘上的位置。
  2. 删除 custom_hooks 目录中的服务器钩子。

链式服务器钩子

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 发起推送的用户或 SSH 密钥的 GitLab 标识符。例如，user-2234 或 key-4。
GL_PROJECT_PATH GitLab 项目路径。
GL_PROTOCOL 用于此更改的协议。以下之一：http（使用 HTTP 的 Git push）、ssh（使用 SSH 的 Git push）或 web（所有其他操作）。
GL_REPOSITORY project-<id>，其中 id 是项目的 ID。
GL_USERNAME 发起推送的用户的 GitLab 用户名。

以下 Git 环境变量适用于 pre-receive 和 post-receive 服务器钩子：

环境变量 描述
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> 推送选项 的值，其中 i 从 0 到 GIT_PUSH_OPTION_COUNT - 1。请参阅 Git pre-receive 文档。

自定义错误消息

当提交被拒绝或在 Git 钩子执行期间发生错误时，您可以让自定义错误消息出现在 GitLab UI 中。要显示自定义错误消息，您的脚本必须：

  • 将自定义错误消息发送到脚本的 stdout 或 stderr。
  • 在每条消息前面加上 GL-HOOK-ERR:，前缀前不要出现任何字符。

例如：

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