• 为存储库设置服务器钩子
  • Gitaly 集群上的服务器钩子
• 为所有存储库创建全局服务器钩子
  • 选择服务器钩子目录
  • 创建全局服务器钩子
• 删除存储库的服务器钩子
• 链式服务器钩子
• 服务器钩子可用的环境变量
• 自定义错误消息

{{< details >}}

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

{{< /details >}}

{{< history >}}

• 在极狐GitLab 15.6 中，从服务器勾子重命名为 Git 服务器勾子。

{{< /history >}}

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

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

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

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

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

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

• Webhooks。
• 极狐GitLab CI/CD。
• Push 规则，用于用户可配置的 Git 钩子接口。

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

为存储库设置服务器钩子

{{< history >}}

• 引入于极狐GitLab 15.11， hooks set 命令替代了直接的文件系统访问。现有的 Git 钩子不需要为 hooks set 命令迁移。

{{< /history >}}

{{< tabs >}}

{{< tab title=”极狐GitLab 15.11 及更高版本” >}}

先决条件：

• 存储名称、Gitaly 配置文件的路径（在 Linux 包实例上默认为 /var/opt/gitlab/gitaly/config.toml），以及存储库的相对路径。
• 每个运行 Gitaly 的服务器上必须安装钩子所需的任何语言运行时和实用程序。

为存储库设置服务器钩子：

1. 创建包含自定义钩子的 tarball：
   1. 编写代码以使服务器钩子按预期运行。极狐GitLab 服务器钩子可以使用任何编程语言。确保顶部的 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 集群，您必须在所有 Gitaly 节点上运行 hooks set 子命令。有关更多信息，请参见 Gitaly 集群上的服务器钩子。

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

{{< /tab >}}

{{< tab title=”极狐GitLab 15.10 及更早版本” >}}

为存储库创建服务器钩子：

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. 编写代码以使服务器钩子按预期运行。极狐GitLab 服务器钩子可以使用任何编程语言。确保顶部的 shebang 反映语言类型。例如，如果脚本是用 Ruby 编写的，shebang 可能是 #!/usr/bin/env ruby。
8. 确保钩子文件不匹配备份文件模式（*~）。
9. 如果您正在使用 Gitaly 集群，您必须在所有 Gitaly 节点上重复此过程。有关更多信息，请参见 Gitaly 集群上的服务器钩子。

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

{{< /tab >}}

{{< /tabs >}}

Gitaly 集群上的服务器钩子

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

复制脚本的位置取决于存储库的存储位置：

• 在极狐GitLab 15.2 及更早版本中，Gitaly 集群使用极狐GitLab 应用程序报告的哈希存储路径。
• 在极狐GitLab 15.3 及更高版本中，新存储库使用 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. 在这个新目录中，添加您的服务器钩子。极狐GitLab 服务器钩子可以使用任何编程语言。确保顶部的 shebang 反映语言类型。例如，如果脚本是用 Ruby 编写的，shebang 可能是 #!/usr/bin/env ruby。
4. 使钩子文件可执行，确保它由 Git 用户拥有，并确保它不匹配备份文件模式（*~）。

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

删除存储库的服务器钩子

{{< history >}}

• 引入于极狐GitLab 15.11， hooks set 命令替代了直接的文件系统访问。

{{< /history >}}

{{< tabs >}}

{{< tab title=”极狐GitLab 15.11 及更高版本” >}}

先决条件：

• 存储库的存储名称和相对路径。

要删除服务器钩子，请传递一个空的 tarball 给 hook set，以指示存储库不应包含任何钩子。例如：

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

{{< /tab >}}

{{< tab title=”极狐GitLab 15.10 及更早版本” >}}

要删除服务器钩子：

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

{{< /tab >}}

{{< /tabs >}}

链式服务器钩子

极狐GitLab 可以在链中执行服务器钩子。极狐GitLab 按以下顺序搜索和执行服务器钩子：

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

在服务器钩子目录中，钩子：

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

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

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

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

以下 Git 环境变量支持 pre-receive 和 post-receive 服务器钩子：

自定义错误消息

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

• 将自定义错误消息发送到脚本的 stdout 或 stderr。
• 在每条消息前加上 GL-HOOK-ERR:，前面没有字符。

例如：

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