密钥推送保护

极狐GitLab 的密钥推送保护可以阻止密钥和 API 令牌等秘密被推送到极狐GitLab。

使用 流水线密钥检测 并结合密钥推送保护来进一步加强安全性。

密钥推送保护工作流程#

密钥推送保护发生在预接收钩子中。当您向极狐GitLab 推送更改时，推送保护会检查每个文件或提交中的密钥。默认情况下，如果检测到密钥，则推送会被阻止。

当推送被阻止时，极狐GitLab 会提示包含以下内容的消息：

• 包含密钥的提交 ID。
• 包含密钥的文件名和行。
• 密钥类型。

例如，以下是使用 Git CLI 推送时返回的消息摘录。当使用其他客户端（包括极狐GitLab Web IDE）时，消息的格式不同，但内容相同。

plain
1remote: PUSH BLOCKED: Secrets detected in code changes
2remote: Secret push protection found the following secrets in commit: 37e54de5e78c31d9e3c3821fd15f7069e3d375b6
3remote:
4remote: -- test.txt:2 极狐GitLab Personal Access Token
5remote:
6remote: To push your changes you must remove the identified secrets.

如果密钥推送保护在您的提交中没有检测到任何密钥，则不会显示消息。

检测到的密钥#

密钥推送保护扫描文件或提交以查找特定模式。每个模式匹配特定类型的密钥。要确认密钥推送保护检测到哪些密钥，请参阅检测到的密钥。仅选择高置信度模式进行密钥推送保护，以尽量减少推送提交时的延迟并减少误报次数。例如，使用自定义前缀的个人访问令牌不会被密钥推送保护检测到。您可以排除选定的密钥，使其不被密钥推送保护检测到。

启用密钥推送保护#

在极狐GitLab Dedicated 和极狐GitLab 私有化部署实例上，您必须：

1. 允许在整个实例上使用密钥推送保护。
2. 为每个项目启用密钥推送保护。

在 JihuLab.com 上，您必须为每个项目启用密钥推送保护。

允许在极狐GitLab 实例中使用密钥推送保护#

在极狐GitLab Dedicated 和极狐GitLab 私有化部署实例上，您必须先允许密钥推送保护，然后才能在项目中启用它。

先决条件：

• 您必须是极狐GitLab 实例的管理员。

要允许在您的极狐GitLab 实例中使用密钥推送保护：

1. 以管理员身份登录您的极狐GitLab 实例。
2. 在左侧边栏底部，选择 管理员。
3. 选择 设置 > 安全与合规。
4. 在 密钥检测下，选择或清除 允许密钥推送保护。

实例上允许使用密钥推送保护。要使用此功能，您必须为每个项目启用它。

在项目中启用密钥推送保护#

先决条件：

• 您必须至少拥有项目的维护者角色。
• 在极狐GitLab 私有化部署实例上，您必须允许在实例上使用密钥推送保护。

要在项目中启用密钥推送保护：

1. 在左侧边栏，选择 搜索或转到 并找到您的项目。
2. 在左侧边栏，选择 安全 > 安全配置。
3. 打开 密钥推送保护 切换。

您还可以通过 API 为群组中的所有项目启用密钥推送保护。

覆盖范围#

密钥推送保护不会在以下情况下阻止密钥：

• 您在推送提交时使用了跳过密钥推送保护选项。
• 密钥已被密钥推送保护排除。
• 密钥位于定义为排除的路径中。

密钥推送保护不会检查提交中的文件，以下情况除外：

• 文件是二进制文件。
• 文件大于 1 MiB。
• 文件的差异补丁大于 1 MiB（使用差异扫描时）。
• 文件被重命名、删除或移动，但内容未更改。
• 文件的内容与源代码中另一个文件的内容相同。
• 文件包含在创建存储库的初始推送中。

差异扫描#

密钥推送保护仅扫描通过 HTTP(S) 和 SSH 推送的提交的差异。如果文件中已经存在密钥而不是更改的一部分，则不会检测到。

对于 Web IDE 推送，将扫描整个文件的内容。要启用 Web IDE 推送的仅差异扫描，请启用 secret_checks_for_web_requests 特性标志。

解决被阻止的推送#

当密钥推送保护阻止推送时，您可以选择：

• 移除密钥
• 跳过密钥推送保护

移除密钥#

移除被阻止的密钥以允许提交被推送到极狐GitLab。移除密钥的方法取决于它最近被提交的时间。以下说明使用 Git CLI 客户端，但您可以使用其他 Git 客户端实现相同结果。

如果被阻止的密钥是通过分支上的最新提交添加的：

1. 从文件中移除密钥。
2. 使用 git add <file-name> 阶段变更。
3. 使用 git commit --amend 修改最新提交以包含更改后的文件。
4. 使用 git push 推送您的更改。

如果被阻止的密钥出现在您的 Git 历史记录中较早的位置：

1. 可选。
2. 从推送错误消息中识别提交 SHA。如果有多个，请使用 git log 找到最早的。
3. 使用 git switch --create copy-branch 创建一个工作复制分支，以便在重置到原始分支时遇到问题时可以重置。
4. 使用 git rebase -i <commit-sha>~1 启动交互式 rebase。
5. 通过将编辑器中的 pick 命令更改为 edit 来标记需要编辑的提交。
6. 从文件中移除密钥。
7. 使用 git add <file-name> 阶段变更。
8. 使用 git commit --amend 提交更改后的文件。
9. 继续 rebase，使用 git rebase --continue，直到所有密钥被移除。
10. 使用 git push --force --set-upstream origin copy-branch:<original-branch> 从复制分支推送您的更改到原始远程分支。
11. 当您对更改感到满意时，请考虑以下可选的清理步骤。
    1. 可选。使用 git branch --delete --force <original-branch> 删除原始分支。
    2. 可选。使用 git branch --move copy-branch <original-branch> 重命名复制分支以替换原始分支。

跳过密钥推送保护#

在某些情况下，可能需要跳过密钥推送保护。例如，开发人员可能需要提交一个用于测试的占位符密钥，或者用户可能希望跳过密钥推送保护以避免 Git 操作超时。

当跳过密钥推送保护时，审计事件 会被记录。审计事件详细信息包括：

• 使用的跳过方法。
• 极狐GitLab 帐户名称。
• 跳过密钥推送保护的日期和时间。
• 推送密钥的项目名称。
• 目标分支。（在极狐GitLab 17.4 中引入）
• 跳过密钥推送保护的提交。（在极狐GitLab 17.9 中引入）

如果启用了流水线密钥检测，则提交的所有内容会在推送到存储库后进行扫描。

要跳过推送中的所有提交的密钥推送保护，可以：

• 如果您使用的是 Git CLI 客户端，指示 Git 跳过密钥推送保护。
• 如果您使用的是其他客户端，请在其中一个提交消息中添加 [skip secret push protection]。

使用 Git CLI 客户端时跳过#

要在使用 Git CLI 客户端时跳过密钥推送保护：

• 使用 推送选项。

  例如，您有多个提交被阻止推送，因为其中一个包含密钥。要跳过密钥推送保护，您可以在 Git 命令中附加推送选项。

  shell
  git push -o secret_push_protection.skip_all

使用任何 Git 客户端时跳过#

要在使用任何 Git 客户端时跳过密钥推送保护：

• 在提交消息的现有行或新行中添加 [skip secret push protection]，然后推送提交。

  例如，您正在使用极狐GitLab Web IDE，多个提交由于其中一个包含密钥而被阻止推送。要跳过密钥推送保护，请编辑最新提交消息并添加 [skip secret push protection]，然后推送提交。

故障排除#

使用密钥推送保护时，您可能会遇到以下情况。

推送意外被阻止#

在极狐GitLab 17.11 之前，密钥推送保护会扫描所有修改文件的内容。如果修改的文件包含密钥，即使该密钥不是差异的一部分，也可能会导致推送意外被阻止。

在极狐GitLab 17.11 和更早版本中，启用 spp_scan_diffs 特性标志以确保仅扫描新提交的更改。要将 Web IDE 更改推送到包含密钥的文件，您需要另外启用 secret_checks_for_web_requests 特性标志。

文件未被扫描#

某些文件被排除在扫描之外。有关详细信息，请参阅覆盖范围。