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

推送规则

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

推送规则是你可以通过用户友好界面启用的 pre-receive Git hooks。推送规则让你能更好地控制什么内容可以推送到你的仓库，什么不可以。虽然 GitLab 提供受保护分支，但你可能需要更具体的规则，例如：

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

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

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

启用全局推送规则

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

先决条件：

  • 你必须是管理员。

创建全局推送规则：

  1. 在左侧边栏底部，选择管理员。
  2. 选择推送规则。
  3. 展开推送规则。
  4. 设置你想要的规则。
  5. 选择保存推送规则。

按项目覆盖全局推送规则

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

  1. 在左侧边栏，选择搜索或跳转并找到你的项目。
  2. 选择设置 > 仓库。
  3. 展开推送规则。
  4. 设置你想要的规则。
  5. 选择保存推送规则。

验证用户

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

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

  • 拒绝未验证用户：提交者邮箱必须匹配用户的已验证邮箱地址或私有提交邮箱地址。
  • 拒绝不一致的用户名：提交作者姓名必须匹配用户的 GitLab 账户名。
  • 检查提交作者是否为 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) 禁用。

验证分支名称

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

一些验证示例：

  • 分支必须以 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 时，推送中的每个文件名都会与禁止的文件名中的正则表达式进行比较。

此功能使用 RE2 语法，不支持正向或负向先行断言。

正则表达式可以：

  • 匹配仓库中任何位置的文件名。
  • 匹配特定位置的文件名。
  • 匹配部分文件名。
  • 按扩展名排除特定文件类型。
  • 组合多个表达式以排除多个模式。

正则表达式示例

这些示例使用常见的正则表达式字符串边界模式：

  • ^：匹配字符串的开头。
  • $：匹配字符串的结尾。
  • \.：匹配字面量句点字符。反斜杠转义句点。
  • \/：匹配字面量正斜杠。反斜杠转义正斜杠。

防止特定文件类型

  • 防止将 .exe 文件推送到仓库中的任何位置：

    \.exe$

防止特定文件

  • 防止推送特定的配置文件：

    • 在仓库根目录：

      ^config\.yml$

    • 在特定目录中：

      ^directory-name\/config\.yml$

  • 在任何位置 - 此示例防止推送任何名为 install.exe 的文件：

    (^|\/)install\.exe$

组合模式

你可以将多个模式组合成一个表达式。此示例组合了前面的所有表达式：

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

要求签名提交

签名提交是用于验证真实性的数字签名。使用拒绝未签名提交推送规则要求所有提交都具有加密签名。

当你启用此规则时：

  • 推送到仓库的所有新提交必须包含有效的加密签名。
  • 签名必须使用支持的签名方法（GPG、SSH 或 X.509）创建。
  • 没有任何签名的提交在推送时会被拒绝。
  • 具有无效或损坏签名的提交会被拒绝。

要启用拒绝未签名提交推送规则：

  1. 在左侧边栏，选择搜索或跳转并找到你的项目。
  2. 选择设置 > 仓库。
  3. 展开推送规则。
  4. 选择拒绝未签名提交。
  5. 选择保存推送规则。

拒绝未通过 DCO 认证的提交

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

相关主题

故障排除

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

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

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

Feature.disable(:reject_unsigned_commits_by_gitlab)

未签名提交出现在提交历史中

拒绝未签名提交推送规则会忽略通过 GitLab（通过 UI 或 API）验证和创建的提交。当此推送规则启用时，如果提交是在 GitLab 本身创建的，未签名提交仍可能出现在提交历史中。

正如预期的那样，在 GitLab 外部创建并推送到仓库的提交会被拒绝。有关更多信息，请参阅 issue #5361。

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

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

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

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

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