Server hooks · Gitlab 中文文檔

# Server hooks > 原文：[https://docs.gitlab.com/ee/administration/server_hooks.html](https://docs.gitlab.com/ee/administration/server_hooks.html) * [Create a server hook for a repository](#create-a-server-hook-for-a-repository) * [Create a global server hook for all repositories](#create-a-global-server-hook-for-all-repositories) * [Chained hooks](#chained-hooks) * [Environment Variables](#environment-variables) * [Transition to Go](#transition-to-go) * [Custom error messages](#custom-error-messages) * [Example custom error message](#example-custom-error-message) # Server hooks[](#server-hooks-core-only "Permalink") 在 GitLab 12.8 中[引入，](https://gitlab.com/gitlab-org/gitlab/-/issues/196051)以取代"自定義掛鉤". Git 支持在不同動作上執行的鉤子. 這些掛鉤在服務器上運行，可用于執行特定的提交策略或基于存儲庫的狀態執行其他任務. Git 支持以下鉤子： * `pre-receive` * `post-receive` * `update` 有關每種鉤子類型的更多信息，請參見[Git 文檔](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#_server_side_hooks) . 服務器端 Git 掛鉤可以配置為： * [A single repository](#create-a-server-hook-for-a-repository). * [All repositories](#create-a-global-server-hook-for-all-repositories). Note the following about server hooks: * 必須在 GitLab 服務器的文件系統上配置服務器掛鉤. 只有 GitLab 服務器管理員才能完成這些任務. 如果您沒有文件系統訪問權限，請參見以下替代方法： * [Webhooks](../user/project/integrations/webhooks.html) . * [亞搏體育 app CI / CD](../ci/README.html) . * [推送規則](../push_rules/push_rules.html) ，用于用戶可配置的 Git 掛鉤界面. * 服務器掛鉤不會復制到[Geo](geo/replication/index.html)輔助節點. ## Create a server hook for a repository[](#create-a-server-hook-for-a-repository "Permalink") 如果您不使用[哈希存儲](repository_storage_types.html#hashed-storage) ，則項目的存儲庫目錄可能與以下說明不完全匹配. 在這種情況下： * 對于從源進行的安裝，路徑通常是`/home/git/repositories/<group>/<project>.git` . * 對于 Omnibus GitLab 安裝，路徑通常為`/var/opt/gitlab/git-data/repositories/<group>/<project>.git` . 請按照以下步驟為存儲庫設置服務器端掛鉤： 1. 導航到" **管理"區域>"項目"** ，然后單擊要向其添加服務器掛鉤的項目. 2. 在出現的頁面上找到**Gitaly 相對路徑** . 這是必須實現服務器掛鉤的地方. 有關解釋相對路徑的信息，請參閱[翻譯哈希存儲路徑](repository_storage_types.html#translating-hashed-storage-paths) . 3. 在文件系統上，在此位置創建一個名為`custom_hooks`的新目錄. 4. 在新的`custom_hooks`目錄中，創建一個名稱與鉤子類型匹配的文件. 例如，對于預接收鉤子，文件名應該是`pre-receive` ，沒有擴展名. 5. 使掛鉤文件可執行，并確保它由 Git 用戶擁有. 6. 編寫代碼以使服務器掛鉤功能按預期方式運行. 掛鉤可以使用任何語言. 確保頂部的[" shebang"](https://en.wikipedia.org/wiki/Shebang_(Unix))正確反映語言類型. 例如，如果腳本在 Ruby 中，則 shebang 可能是`#!/usr/bin/env ruby` . 假設正確執行了掛鉤代碼，則將適當地執行掛鉤代碼. ## Create a global server hook for all repositories[](#create-a-global-server-hook-for-all-repositories "Permalink") 要創建適用于您實例中所有存儲庫的 Git 掛鉤，請設置一個全局服務器掛鉤. 默認的全局服務器掛鉤目錄位于 GitLab Shell 目錄中. 在那里添加的任何鉤子都適用于所有存儲庫. 默認目錄： * 對于從源代碼進行的安裝，通常是`/home/git/gitlab-shell/hooks` . * 對于 Omnibus GitLab，安裝通常是`/opt/gitlab/embedded/service/gitlab-shell/hooks` . 要將其他目錄用于全局服務器掛鉤， `custom_hooks_dir`在 Gitaly 配置中設置`custom_hooks_dir` ： * 對于 Omnibus 安裝，此設置在`gitlab.rb` . * 對于源代碼安裝，配置位置取決于 GitLab 版本. 對于： * GitLab 13.0 及更早版本，在`gitlab-shell/config.yml` . * GitLab 13.1 及更高版本，在`[hooks]`部分的`gitaly/config.toml`進行設置. **注意：** `gitlab-shell/config.yml`的`custom_hooks_dir`值在 GitLab 13.1 和更高版本中仍然被接受，如果`gitaly/config.toml`的值是空白或不存在. 請按照以下步驟為所有存儲庫設置全局服務器掛鉤： 1. 在 GitLab 服務器上，導航到配置的全局服務器掛鉤目錄. 2. 在此位置創建一個新目錄. 根據掛鉤的類型，它可以是`pre-receive.d` ， `post-receive.d`或`update.d`目錄. 3. 在這個新目錄中，添加您的鉤子. 掛鉤可以使用任何語言. 確保頂部的[" shebang"](https://en.wikipedia.org/wiki/Shebang_(Unix))正確反映語言類型. 例如，如果腳本在 Ruby 中，則 shebang 可能是`#!/usr/bin/env ruby` . 4. 使掛鉤文件可執行，并確保它由 Git 用戶擁有. 現在，測試掛鉤以檢查其是否正常運行. ## Chained hooks[](#chained-hooks "Permalink") 在 GitLab Shell 4.1.0 和 GitLab 8.15 中[引入](https://gitlab.com/gitlab-org/gitlab-shell/-/merge_requests/93) . 可以按鏈執行[每個項目](#create-a-server-hook-for-a-repository)或[全局](#create-a-global-server-hook-for-all-repositories)設置的服務器掛鉤. 搜索服務器掛鉤并按以下優先級順序執行： * 內置的 GitLab 服務器掛鉤. 這些不是用戶可定制的. * `<project>.git/custom_hooks/<hook_name>` ：每個項目的掛鉤. 保留它是為了向后兼容. * `<project>.git/custom_hooks/<hook_name>.d/*` ：每個項目掛鉤的位置. * `<custom_hooks_dir>/<hook_name>.d/*` ：除編輯器備份文件之外的所有可執行全局掛鉤文件的位置. 在目錄中，服務器掛鉤： * 按字母順序執行. * 當鉤子以非零值退出時，停止執行. Note: * `<hook_name>.d`必須為`pre-receive.d` ， `post-receive.d`或`update.d`才能正常工作. 其他任何名稱都將被忽略. * `.d`目錄中的文件必須是可執行文件，并且與備份文件模式（ `*~` ）不匹配. * 對于`<project>.git` ，你需要[翻譯](repository_storage_types.html#translating-hashed-storage-paths)你的項目名稱為散列存儲格式 GitLab 用途. ## Environment Variables[](#environment-variables "Permalink") 以下環境變量集可用于服務器掛鉤. | 環境變量 | Description | | --- | --- | | `GL_ID` | 啟動推送的用戶的 GitLab 標識符. 例如， `user-2234` | | `GL_PROJECT_PATH` | （GitLab 13.2 和更高版本）GitLab 項目路徑 | | `GL_PROTOCOL` | （GitLab 13.2 和更高版本）與 push 一起使用的協議 | | `GL_REPOSITORY` | `project-<id>` ，其中`id`是項目的 ID | | `GL_USERNAME` | 啟動推送的用戶的 GitLab 用戶名 | 接收前和接收后服務器掛鉤也可以訪問以下 Git 環境變量. | 環境變量 | Description | | --- | --- | | `GIT_ALTERNATE_OBJECT_DIRECTORIES` | 隔離環境中的備用對象目錄. 請參閱[Git `receive-pack`文檔](https://git-scm.com/docs/git-receive-pack#_quarantine_environment) . | | `GIT_OBJECT_DIRECTORY` | GitLab project path in the quarantine environment. See [Git `receive-pack` documentation](https://git-scm.com/docs/git-receive-pack#_quarantine_environment). | | `GIT_PUSH_OPTION_COUNT` | 推送選項的數量. 請參閱[Git `pre-receive`文檔](https://git-scm.com/docs/githooks#pre-receive) . | | `GIT_PUSH_OPTION_<i>` | `i`從`0`到`GIT_PUSH_OPTION_COUNT - 1`的推送選項的值. 請參閱[Git `pre-receive`文檔](https://git-scm.com/docs/githooks#pre-receive) . | **注意：**雖然其他環境變量可以傳遞給服務器掛鉤，但是您的應用程序不應依賴它們，因為它們可以更改. ## Transition to Go[](#transition-to-go "Permalink") 在 GitLab 13.2 中使用功能標記引入. 以下服務器掛鉤已在 Go 中重新實現： * `pre-receive` ，默認情況下使用 Go 實現. 要改用 Ruby 實現，請[禁用](../operations/feature_flags.html#enable-or-disable-feature-flag-strategies) `:gitaly_go_preceive_hook`功能標記. * `update` ，默認使用 Go 實現. 要改用 Ruby 實現，請[禁用](../operations/feature_flags.html#enable-or-disable-feature-flag-strategies) `:gitaly_go_update_hook`功能標志. * `post-receive` ，但是默認情況下使用 Ruby 實現. 要改用 Go 實現，請[啟用](../operations/feature_flags.html#enable-or-disable-feature-flag-strategies) `:gitaly_go_postreceive_hook`功能標志. ## Custom error messages[](#custom-error-messages "Permalink") 在 GitLab 8.10 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5073) . 要在拒絕提交或在 Git 掛鉤期間發生錯誤時在 GitLab 的 UI 中顯示自定義錯誤消息，您的腳本應： * 將自定義錯誤消息發送到腳本的`stdout`或`stderr` . * 給每條消息加上`GL-HOOK-ERR:`前綴，前綴前沒有字符. ### Example custom error message[](#example-custom-error-message "Permalink") 用 Bash 編寫的該鉤子腳本在 GitLab 的 UI 中生成以下消息： ``` #!/bin/sh echo "GL-HOOK-ERR: My custom error message."; exit 1 ``` [![Custom message from custom Git hook](https://img.kancloud.cn/fe/eb/feeb65acd9852a683927c4f35d7c13d3_850x351.png)](img/custom_hooks_error_msg.png)