使用 GPG 签名提交

您可以使用 GPG (GNU Privacy Guard) 密钥对在极狐GitLab 仓库中所做的提交进行签名。当您将加密签名添加到您的提交时,您提供了额外的保证,即提交来自您,而不是冒充者。如果极狐GitLab 可以使用公共 GPG 密钥验证提交作者的身份,则提交在 GitLab UI 中标记为 已验证。然后,您可以为您的项目配置推送规则,拒绝未使用 GPG 签名的单个提交,或拒绝来自未验证用户的所有提交。

note 极狐GitLab 使用术语 GPG 来表示所有 OpenPGP、PGP 和 GPG 相关的材料和实现。

对于极狐GitLab,考虑已验证的提交:

  • 提交者必须具有 GPG 公钥/私钥对。
  • 提交者的公钥必须上传到他们的极狐GitLab 账户。
  • GPG 公钥中的其中一个电子邮件地址必须与极狐GitLab 中提交者使用的已验证电子邮件地址匹配。要将此地址保密,请使用极狐GitLab 在您的个人资料中提供的自动生成的私人提交电子邮件地址。
  • 提交者的电子邮件地址必须与 GPG 密钥中经过验证的电子邮件地址相匹配。

极狐GitLab 使用自己的密钥环来验证 GPG 签名。它不访问任何公钥服务器。

不支持 GPG 验证标签。

查看用户的公共 GPG 密钥

要查看用户的公共 GPG 密钥,您可以:

  • 转到 https://gitlab.example.com/<USERNAME>.gpg。如果用户配置了 GPG 密钥,系统将显示 GPG 密钥,或者为没有配置 GPG 密钥的用户显示空白页面。
  • 转到用户的个人资料(例如https://gitlab.example.com/<USERNAME>)。在用户个人资料的右上角,选择 查看公共 GPG 密钥 ( )。

配置提交签名

要签名提交,您必须同时配置本地计算机和极狐GitLab 账户:

  1. 创建 GPG 密钥
  2. 将 GPG 密钥添加到您的账户
  3. 将您的 GPG 密钥与 Git 关联
  4. 签名您的 Git 提交

创建 GPG 密钥

如果您还没有 GPG 密钥,请创建:

  1. 为您的操作系统安装 GPG 。如果您的操作系统安装了 gpg2,请在本页的命令中将 gpg 替换为 gpg2
  2. 要生成您的密钥对,请运行适合您的 gpg 版本的命令:

    # Use this command for the default version of GPG, including
    # Gpg4win on Windows, and most macOS versions:
    gpg --gen-key
    
    # Use this command for versions of GPG later than 2.1.17:
    gpg --full-gen-key
    
  3. 选择您的密钥应该使用的算法,或按 Enter 选择默认选项 RSA and RSA
  4. 选择密钥长度,以位为单位。建议使用 4096 位密钥。
  5. 指定密钥的有效期。这个值是主观的,默认值是没有过期。
  6. 要确认您的答案,请输入 y
  7. 输入您的姓名。
  8. 输入您的电子邮件地址。它必须与您 GitLab 账户中的已验证电子邮件地址匹配。
  9. 可选。输入要在您的姓名后的括号中显示的评论。
  10. GPG 显示您目前输入的信息。编辑信息或按 O(表示 Okay)继续。
  11. 输入强密码,然后再次输入确认。
  12. 要列出您的私人 GPG 密钥,请运行以下命令,将 <EMAIL> 替换为您在生成密钥时使用的电子邮件地址:

    gpg --list-secret-keys --keyid-format LONG <EMAIL>
    
  13. 在输出中,识别 sec 行,并复制 GPG 密钥 ID。它在 / 字符之后开始。在此示例中,密钥 ID 为 30F2B65B9246B6CA

    sec   rsa4096/30F2B65B9246B6CA 2017-08-18 [SC]
          D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
    uid                   [ultimate] Mr. Robot <your_email>
    ssb   rsa4096/B7ABC0813E4028C0 2017-08-18 [E]
    
  14. 要显示关联的公钥,请运行以下命令,将 <ID> 替换为上一步中的 GPG 密钥 ID:

    gpg --armor --export <ID>
    
  15. 复制公钥,包括 BEGIN PGP PUBLIC KEY BLOCKEND PGP PUBLIC KEY BLOCK 行。您在下一步中需要此密钥。

将 GPG 密钥添加到您的账户

要将 GPG 密钥添加到您的用户设置:

  1. 登录极狐GitLab。
  2. 在右上角,选择您的头像。
  3. 选择 编辑个人资料
  4. 在左侧边栏中,选择 GPG 密钥 ( )。
  5. 密钥 中,粘贴您的 公共 密钥。
  6. 要将密钥添加到您的账户,请选择 添加密钥。极狐GitLab 显示密钥的指纹、电子邮件地址和创建日期:

    GPG key single page

添加密钥后,您将无法对其进行编辑。您可以删除有问题的密钥并重新添加它。

将您的 GPG 密钥与 Git 关联

创建 GPG 密钥并将其添加到您的账户后,您必须配置 Git 以使用此密钥:

  1. 运行以下命令列出您刚刚创建的 GPG 私钥,将 <EMAIL> 替换为您的密钥的电子邮件地址:

    gpg --list-secret-keys --keyid-format LONG <EMAIL>
    
  2. 复制以 sec 开头的 GPG 私钥 ID。在本例中,私钥 ID 为 30F2B65B9246B6CA

    sec   rsa4096/30F2B65B9246B6CA 2017-08-18 [SC]
          D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
    uid                   [ultimate] Mr. Robot <your_email>
    ssb   rsa4096/B7ABC0813E4028C0 2017-08-18 [E]
    
  3. 运行此命令配置 Git 以使用您的密钥签名您的提交,将 <KEY ID> 替换为您的 GPG 密钥 ID:

    git config --global user.signingkey <KEY ID>
    
  4. 可选。如果 Git 使用 gpg 并且您收到诸如 secret key not availablegpg: signing failed: secret key not available 之类的错误,请运行以下命令以使用 gpg2 代替:

    git config --global gpg.program gpg2
    

签名您的 Git 提交

将公钥添加到您的账户后,您可以手动签名单个提交,或将 Git 配置为默认为已签名的提交:

  • 手动签名单个 Git 提交:
    1. -S 标志添加到您要签名的任何提交:

      git commit -S -m "My commit message"
      
    2. 询问时输入您的 GPG 密钥的密码。
    3. 推送到极狐GitLab 并检查您的提交是否经过验证。
  • 默认情况下,通过运行以下命令对所有 Git 提交进行签名:

    git config --global commit.gpgsign true
    

验证提交

您可以查看合并请求或整个项目的提交:

  1. 查看项目的提交:
    1. 在左侧边栏中,选择 搜索或转到 并找到您的项目。
    2. 在左侧边栏中,选择 代码 > 提交
  2. 查看合并请求的提交:
    1. 在左侧边栏中,选择 搜索或转到 并找到您的项目。
    2. 在左侧边栏中,选择 合并请求,然后选择您的合并请求。
    3. 选择 提交
  3. 确定您要查看的提交。根据 GPG 签名的验证状态,已签名的提交会显示 已验证未验证 徽章。未签名的提交不显示徽章:

    Signed and unsigned commits

  4. 要显示提交的签名详细信息,请选择 GPG 徽章:

    Signed commit with verified signature

    Signed commit with unverified signature

撤销 GPG 密钥

如果 GPG 密钥被泄露,请撤销它。撤销密钥会更改未来和过去的提交:

  • 此密钥签名的过去提交被标记为未验证。
  • 由该密钥签名的未来提交被标记为未验证。

撤销 GPG 密钥:

  1. 在右上角,选择您的头像。
  2. 选择 编辑个人资料
  3. 在左侧边栏中,选择GPG 密钥 ( )。
  4. 选择要删除的 GPG 密钥旁边的 撤销

删除 GPG 密钥

当您从极狐GitLab 账户中删除 GPG 密钥时:

  • 使用此密钥签名的先前提交仍然为已验证。
  • 尝试使用此密钥的未来提交(包括任何已创建但尚未推送的提交)为未验证。

要从您的账户中删除 GPG 密钥:

  1. 在右上角,选择您的头像。
  2. 选择 编辑个人资料
  3. 在左侧边栏中,选择 GPG 密钥 ( )。
  4. 选择要删除的 GPG 密钥旁边的 删除 ( )。

如果您必须取消验证未来和过去的提交,请改为撤销关联的 GPG 密钥

故障排除

修复签名提交的验证问题

可以使用 X.509 证书或 GPG 密钥对提交进行签名。两种方法的验证过程可能因多种原因而失败:

描述 修复方法
UNVERIFIED 提交签名无效。 使用有效签名签署提交。
SAME_USER_DIFFERENT_EMAIL 用于签署提交的 GPG 密钥不包含提交者电子邮件,但确实包含提交者的不同有效电子邮件。 修改提交,使用与 GPG 密钥匹配的电子邮件地址,或更新 GPG 密钥,包含电子邮件地址
OTHER_USER 签名和 GPG 密钥是有效的,但密钥属于与提交者不同的用户。 修改提交来使用正确的电子邮件地址,或修改提交来使用与您的用户关联的 GPG 密钥。
UNVERIFIED_KEY 与 GPG 签名关联的密钥没有与提交者关联的经过验证的电子邮件地址。 添加并验证电子邮件到您的极狐GitLab 配置文件,更新 GPG 密钥来包含电子邮件地址,或修改提交来使用不同的提交者电子邮件地址。
UNKNOWN_KEY 极狐GitLab 不知道与此提交的 GPG 签名关联的 GPG 密钥。 添加 GPG 密钥到您的极狐GitLab 配置文件。
MULTIPLE_SIGNATURES 已为提交找到多个 GPG 或 X.509 签名。 修改提交,仅使用一个 GPG 或 X.509 签名。