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

使用 GPG 签名提交

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

您可以使用 GPG (GNU Privacy Guard) 密钥为在 GitLab 仓库中创建的提交进行签名。

GitLab 使用术语 GPG 来指代所有 OpenPGP、PGG 和 GPG 相关的材料和实现。

对于 GitLab 来说，一个提交被认为是已验证的，需要满足以下条件：

  • 提交者必须拥有一对 GPG 公钥/私钥。
  • 提交者的公钥必须上传到其 GitLab 账户。
  • GPG 公钥中的某个电子邮件地址必须与提交者在 GitLab 中使用的已验证电子邮件地址匹配。为了保持此地址的私密性，请使用您个人资料中 GitLab 提供的自动生成的 私有提交电子邮件地址。
  • 提交者的电子邮件地址必须与 GPG 密钥中的已验证电子邮件地址匹配。

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

不支持 GPG 验证的标签。

有关 GPG 的更多详细信息，请参阅 相关主题列表。

查看用户的公钥

要查看用户的公钥，您可以：

  • 访问 https://gitlab.example.com/<USERNAME>.gpg。如果用户已配置 GPG 密钥，GitLab 会显示该密钥；对于未配置 GPG 密钥的用户，则会显示空白页面。
  • 访问用户的个人资料（例如 https://gitlab.example.com/<USERNAME>）。在用户个人资料的右上角，选择 查看公钥 ( key )。仅当用户已配置密钥时才会显示此按钮。

配置提交签名

要对提交进行签名，您必须配置本地机器和 GitLab 账户：

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

创建 GPG 密钥

如果您还没有 GPG 密钥，请创建一个：

  1. 为您的操作系统 安装 GPG。 如果您的操作系统已安装 gpg2，请将此页面中的 gpg 替换为 gpg2。

  2. 为生成您的密钥对，运行适合您 gpg 版本的命令：

    # 对于默认版本的 GPG，包括 Windows 上的 Gpg4win 和大多数 macOS 版本，使用此命令：
gpg --gen-key

# 对于 2.1.17 之后的 GPG 版本，使用此命令：
gpg --full-gen-key

  3. 选择密钥应使用的算法，或按 Enter 选择默认选项 RSA and RSA。

  4. 选择密钥长度（以位为单位）。GitLab 推荐 4096 位的密钥。

  5. 指定密钥的有效期。此值是主观的，默认值为永不过期。

  6. 确认您的答案，输入 y。

  7. 输入您的姓名。

  8. 输入您的电子邮件地址。它必须与您 GitLab 账户中的 已验证电子邮件地址 匹配。

  9. 可选。输入要在您姓名后以括号显示的注释。

  10. GPG 显示您已输入的信息。编辑信息或按 O（表示 Okay）继续。

  11. 输入强密码，然后再次输入以确认。

  12. 要列出您的私钥，运行此命令，将 <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 BLOCK 和 END PGP PUBLIC KEY BLOCK 行。您在下一步中需要此密钥。

将 GPG 密钥添加到您的账户

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

  1. 登录 GitLab。
  2. 在左侧边栏中，选择您的头像。
  3. 选择 编辑个人资料。
  4. 选择 GPG 密钥 ( key )。
  5. 选择 添加新密钥。
  6. 在 密钥 中，粘贴您的公钥。
  7. 要将密钥添加到您的账户，选择 添加密钥。

GitLab 显示密钥的指纹、电子邮件地址和创建日期。

添加密钥后，您无法编辑它。相反，请删除有问题的密钥并重新添加。

将您的 GPG 密钥与 Git 关联

在您 创建 GPG 密钥 和 将其添加到您的账户 后，您必须配置 Git 以使用此密钥：

  1. 运行此命令以列出您刚创建的私钥，将 <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>

签名您的 Git 提交

在您 将公钥添加到您的账户 后，您可以手动签名单个提交，或配置 Git 默认签名提交：

  • 手动签名单个 Git 提交：

    1. 为任何要签名的提交添加 -S 标志：

      git commit -S -m "我的提交消息"

    2. 当提示时输入您的 GPG 密钥的密码短语。

    3. 推送到 GitLab 并检查您的提交 是否已验证。

  • 通过运行此命令默认签名所有 Git 提交：

    git config --global commit.gpgsign true

条件设置签名密钥

如果您为不同目的（如工作和个人使用）维护签名密钥，请在您的 .gitconfig 文件中使用 IncludeIf 语句来设置您用于签名提交的密钥。

先决条件：

  • 需要 Git 版本 2.13 或更高版本。

  1. 在与主 ~/.gitconfig 文件相同的目录中，创建第二个文件，例如 .gitconfig-gitlab。

  2. 在您的主 ~/.gitconfig 文件中，添加您在非 GitLab 项目中工作的 Git 设置。

  3. 将以下信息附加到主 ~/.gitconfig 文件的末尾：

    # 此文件的内容仅包含 GitLab.com URL
[includeIf "hasconfig:remote.*.url:https://gitlab.com/**"]

# 编辑此行以指向您的备用配置文件
path = ~/.gitconfig-gitlab

  4. 在您的备用 .gitconfig-gitlab 文件中，添加在提交到 GitLab 仓库时要使用的配置覆盖。除非您明确覆盖，否则主 ~/.gitconfig 文件中的所有设置都会保留。在此示例中，

    # 备用 ~/.gitconfig-gitlab 文件
# 这些值用于匹配字符串 'gitlab.com' 的仓库，
# 并覆盖 ~/.gitconfig 中相应的值

[user]
email = you@example.com
signingkey = <KEY ID>

[commit]
gpgsign = true

撤销 GPG 密钥

如果 GPG 密钥被泄露，请撤销它。撤销密钥会改变未来和过去的提交：

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

要撤销 GPG 密钥：

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

删除 GPG 密钥

当您从 GitLab 账户中删除 GPG 密钥时：

  • 使用此密钥签名的先前提交保持验证状态。
  • 尝试使用此密钥的未来提交（包括已创建但尚未推送的提交）将不被验证。

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

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

如果您必须使未来的和过去的提交都变为未验证状态，请改为 撤销关联的 GPG 密钥。

相关主题

故障排除

私钥不可用

如果您收到错误 secret key not available 或 gpg: signing failed: secret key not available，请尝试使用 gpg2 而不是 gpg：

git config --global gpg.program gpg2

如果您的 GPG 密钥受密码保护且密码输入提示未出现，请将 export GPG_TTY=$(tty) 添加到您 shell 的 rc 文件中（通常是 ~/.bashrc 或 ~/.zshrc）

GPG 签名数据失败

如果您的 GPG 密钥受密码保护，并且您收到以下错误之一：

error: gpg failed to sign the data
fatal: failed to write commit object
gpg: signing failed: Inappropriate ioctl for device

如果密码输入提示未出现：

  1. 在文本编辑器中打开您 shell 的配置文件，通常是 ~/.bashrc 或 ~/.zshrc。

  2. 将以下行添加到文件中：

    export GPG_TTY=$(tty)

  3. 保存文件并退出文本编辑器。

  4. 应用更改。选择以下方法之一：

    • 重新启动您的终端。
    • 运行 source ~/.bashrc 或 source ~/.zshrc。

具体步骤可能因您的操作系统和 shell 配置而异。