推送规则

推送规则是您可以在用户友好的界面中启用的pre-receive Git hooks。推送规则使您可以更好地控制可以推送到存储库的内容。虽然 GitLab 提供了受保护的分支，但您可能需要更具体的规则，例如：

  • 评估提交的内容。
  • 确认提交消息符合预期格式。
  • 强制执行分支命名规则。
  • 评估文件的详细信息。
  • 防止删除 Git 标签。

极狐GitLab 在推送规则中使用 RE2 语法进行正则表达式匹配。您可以在regex101 正则表达式测试器上测试它们。每个正则表达式限制为 511 个字符。

对于自定义推送规则，请使用服务器钩子。

启用全局推送规则

您可以创建所有新项目继承的推送规则，但它们可以在项目或组中被覆盖。配置全局推送规则后创建的所有项目都将继承此配置。然而，必须手动更新每个现有项目，使用每个项目覆盖全局推送规则中描述的过程。

先决条件：

  • 您必须是管理员。

要创建全局推送规则：

  1. 在左侧边栏底部，选择 Admin。
  2. 选择 Push rules。
  3. 展开 Push rules。
  4. 设置您想要的规则。
  5. 选择 Save push rules。

每个项目覆盖全局推送规则

单个项目的推送规则会覆盖全局推送规则。要覆盖特定项目的全局推送规则，或更新现有项目的规则以匹配新的全局推送规则：

  1. 在左侧边栏，选择 Search or go to 并找到您的项目。
  2. 选择 Settings > Repository。
  3. 展开 Push rules。
  4. 设置您想要的规则。
  5. 选择 Save push rules。

验证用户

使用这些规则来验证进行提交的用户。

注意： 这些推送规则仅适用于提交，不适用于标签。

  • 拒绝未验证的用户：用户必须有一个确认的电子邮件地址。
  • 检查提交作者是否为极狐GitLab 用户：提交作者和提交者必须有一个 GitLab 验证的电子邮件地址。
  • 提交作者的电子邮件：作者和提交者的电子邮件地址必须匹配正则表达式。要允许任何电子邮件地址，请留空。

验证提交消息

使用这些规则来验证您的提交消息。

  • 在提交消息中要求表达式：消息必须匹配表达式。要允许任何提交消息，请留空。使用多行模式，可以通过使用 (?-m) 禁用它。一些验证示例：

    • JIRA\-\d+ 要求每个提交都引用一个 Jira 议题，例如 Refactored css. Fixes JIRA-123。
    • [[:^punct:]]\b$ 如果最后一个字符是标点符号，则拒绝提交。单词边界字符（\b）防止误报，因为 Git 会在提交消息末尾添加换行符（\n）。

    在极狐GitLab UI 中创建的提交消息将 \r\n 设置为换行符。在正则表达式中使用 (\r\n?|\n) 代替 \n 以正确匹配它。

    例如，给定以下多行提交描述：

    JIRA:
Description

    您可以使用此正则表达式进行验证：JIRA:(\r\n?|\n)\w+。

    • 拒绝提交消息中的表达式：提交消息不得匹配该表达式。要允许任何提交消息，请留空。 使用多行模式，可以通过使用 (?-m) 禁用它。

    拒绝未签署的提交

    • 在极狐GitLab 15.5 中引入。

    使用开发者证书 (DCO) 签署的提交，证明贡献者编写了该提交中的代码或有权提交该代码。 您可以要求所有提交到您的项目的提交都符合 DCO。此推送规则要求每个提交消息中都有一个 Signed-off-by: 标记，并拒绝任何缺少该标记的提交。

    验证分支名称

    要验证您的分支名称，请输入正则表达式到 Branch name 中。 要允许任何分支名称，请留空。您的默认分支始终被允许。出于安全原因，某些格式的分支名称默认受限。名称包含 40 个十六进制字符，类似于 Git 提交哈希的名称是禁止的。

    一些验证示例：

    • 分支必须以 JIRA- 开头。
    ^JIRA-

  • 分支名称必须以 -JIRA 结尾。

    -JIRA$

  • 分支名称必须介于 4 到 15 个字符之间， 只接受小写字母、数字和短划线。

    ^[a-z0-9\\-]{4,15}$

防止意外后果

使用这些规则来防止意外后果。

验证文件

使用这些规则来验证提交中包含的文件。

  • 防止推送秘密文件：文件不得包含秘密。
  • 禁止的文件名：不在存储库中的文件不得匹配正则表达式。要允许所有文件名，请留空。请参阅常见示例。
  • 最大文件大小：添加或更新的文件不得超过此文件大小（以 MB 为单位）。要允许任何大小的文件，请设置为 0。由 Git LFS 跟踪的文件不受此限制。

防止将秘密推送到存储库

切勿将秘密（如凭证文件和 SSH 私钥）提交到版本控制系统。在极狐GitLab 中，您可以使用预定义的文件列表来阻止这些文件进入存储库。包含匹配列表中文件的合并请求将被阻止。此推送规则不会限制已提交到存储库中的文件。您必须使用每个项目覆盖全局推送规则中描述的过程来更新现有项目的配置以使用此规则。

此规则阻止的文件如下所示。有关完整的标准列表，请参阅files_denylist.yml。

  • AWS CLI 凭证文件：

    • .aws/credentials
    • aws/credentials
    • homefolder/aws/credentials

  • 私有 RSA SSH 密钥：

    • /ssh/id_rsa
    • /.ssh/personal_rsa
    • /config/server_rsa
    • id_rsa
    • .id_rsa

  • 私有 DSA SSH 密钥：

    • /ssh/id_dsa
    • /.ssh/personal_dsa
    • /config/server_dsa
    • id_dsa
    • .id_dsa

  • 私有 ED25519 SSH 密钥：

    • /ssh/id_ed25519
    • /.ssh/personal_ed25519
    • /config/server_ed25519
    • id_ed25519
    • .id_ed25519

  • 私有 ECDSA SSH 密钥：

    • /ssh/id_ecdsa
    • /.ssh/personal_ecdsa
    • /config/server_ecdsa
    • id_ecdsa
    • .id_ecdsa

  • 私有 ECDSA_SK SSH 密钥：

    • /ssh/id_ecdsa_sk
    • /.ssh/personal_ecdsa_sk
    • /config/server_ecdsa_sk
    • id_ecdsa_sk
    • .id_ecdsa_sk

  • 私有 ED25519_SK SSH 密钥：

    • /ssh/id_ed25519_sk
    • /.ssh/personal_ed25519_sk
    • /config/server_ed25519_sk
    • id_ed25519_sk
    • .id_ed25519_sk

  • 任何以以下后缀结尾的文件：

    • *.pem
    • *.key
    • *.history
    • *_history ### 按名称禁止文件

    在 Git 中，文件名包括文件的名称和名称前的所有目录。当您 git push 时，推送中的每个文件名都会与 禁止的文件名 中的正则表达式进行比较。

    禁止的文件名 推送规则中的正则表达式可以包含多个独立的匹配项以排除文件。您可以广泛地匹配存储库中任何位置的文件名，或仅在某些位置进行限制。文件名匹配也可以是部分匹配，并通过扩展名排除文件类型。

    这些示例使用正则表达式（正则表达式）字符串边界字符来匹配字符串的开头（^）及其结尾（$）。它们还包括目录路径或文件名可以包含 . 或 / 的情况。如果要将这些特殊的正则表达式字符用作匹配条件中的标准字符，则必须使用反斜杠 \\ 对其进行转义。

    • 防止将 .exe 文件推送到存储库中的任何位置 - 此正则表达式匹配任何以 .exe 结尾的文件名：

      \.exe$

    • 防止将特定配置文件推送到存储库根目录

      ^config\.yml$

    • 防止将特定配置文件推送到已知目录

      ^directory-name\/config\.yml$

    • 防止将特定文件推送到存储库中的任何位置 - 此示例测试任何名为 install.exe 的文件。括号表达式 (^|\/) 匹配目录分隔符后的文件或存储库根目录中的文件：

      (^|\/)install\.exe$

    • 将所有先前的表达式组合成一个表达式 - 前面的表达式依赖于字符串结尾字符 $。我们可以将每个表达式的这一部分移动到匹配条件集合的末尾，并将其附加到所有匹配项：

      (\.exe|^config\.yml|^directory-name\/config\.yml|(^|\/)install\.exe)$

相关主题

故障排除

拒绝未签署的提交推送规则禁用 Web IDE

如果项目具有 拒绝未签署的提交 推送规则，用户无法通过极狐GitLab Web IDE 创建提交。

要允许在具有此推送规则的项目中通过 Web IDE 提交，极狐GitLab 管理员必须使用标志禁用功能标志 reject_unsigned_commits_by_gitlab。

Feature.disable(:reject_unsigned_commits_by_gitlab)

在极狐GitLab UI 中创建的未签署提交

拒绝未签署的提交 推送规则忽略由极狐GitLab（通过 UI 或 API）认证并创建的提交。当启用此推送规则时，如果提交是在极狐GitLab 本身创建的，未签署的提交仍可能出现在提交历史记录中。正如预期的那样，在极狐GitLab 之外创建并推送到存储库的提交将被拒绝。有关此问题的更多信息，请阅读议题 #19185。

批量更新 所有 项目的推送规则

要将所有项目的推送规则更新为相同的规则，请使用 Rails 控制台，或编写脚本使用 推送规则 API 端点 更新每个项目。

例如，要启用 检查提交作者是否为 GitLab 用户 和 不允许用户使用 git push 删除 Git 标签 复选框，并通过 Rails 控制台创建仅允许特定电子邮件域提交的过滤器：

警告： 更改数据的命令如果未正确运行或在正确的条件下运行，可能会造成损害。始终在测试环境中首先运行命令，并准备好备份实例以进行恢复。

Project.find_each do |p|
  pr = p.push_rule || PushRule.new(project: p)
  # 检查提交作者是否为 GitLab 用户
  pr.member_check = true
  # 不允许用户使用 `git push` 删除 Git 标签
  pr.deny_delete_tag = true
  # 提交作者的电子邮件
  pr.author_email_regex = '@domain\.com$'
  pr.save!
end