Git 提交 GPG 签名配置
bash gpg --version
如果未安装，请根据你的操作系统执行：
- **Ubuntu/Debian**：`sudo apt install gnupg`
- **macOS**：`brew install gnupg`
- **Windows**：下载并安装 [Gpg4win](https://www.gpg4win.org/)
## 生成 GPG 密钥对
### 生成新密钥
运行以下命令进入交互式生成向导：
```bash
gpg --full-generate-key
按提示依次选择：
- 密钥类型：选择
RSA and RSA（默认），或按你的安全需求选择ECC（更现代）。 - 密钥长度：建议至少 4096 位。
- 有效期限：可以设为
0表示永不过期，或按需求选择时间。 - 用户标识：
- 真实姓名：推荐使用你的常用名字（如
Zhang San） - 电子邮件地址：必须与你 Git 配置中的
user.email完全一致 - 注释：可选，如
Git signing key
- 真实姓名：推荐使用你的常用名字（如
- 密码短语：为密钥设置一个强密码，每次签名时可能需要输入（可以配合 gpg-agent 缓存，稍后说明）。
生成完成后你会看到类似输出：
pub rsa4096 2025-03-20 [SC]
ABCDEF1234567890ABCDEF1234567890ABCDEF12
uid Zhang San <zhangsan@example.com>
sub rsa4096 2025-03-20 [E]
记下显示的密钥 ID（上面示例中的 ABCDEF1234567890ABCDEF1234567890ABCDEF12），后续配置会用到。
列出已有密钥
若你需要查看已存在的密钥：
gpg --list-secret-keys --keyid-format=long
输出的 sec 段落中，rsa4096/ 后面的字符串即为密钥 ID，例如：
sec rsa4096/ABCDEF1234567890 2025-03-20 [SC]
密钥 ID 可以取完整的 40 位，或后 16 位（例如 ABCDEF1234567890）。在 Git 配置中推荐使用完整密钥 ID。
配置 Git 使用 GPG 签名
告诉 Git 使用哪个密钥
设置签名所用的 GPG 密钥：
git config --global user.signingkey ABCDEF1234567890
将 ABCDEF1234567890 替换为你的实际密钥 ID。
启用自动签名
- 对每次提交自动签名（推荐）：
git config --global commit.gpgsign true
-
如果只想对单个仓库启用，去掉
--global并在对应仓库内执行。 -
若只想手动签名某次提交，可以在
git commit时加上-S参数：
git commit -S -m "your message"
配置 GPG 程序路径（跨平台兼容）
某些系统下 Git 可能找不到 GPG 程序，可以明确指定路径：
git config --global gpg.program gpg
如果使用 GPG2，确保程序名为 gpg2 或设置正确。Windows 下 Git for Windows 通常自带 gpg，路径为 C:\Program Files\Git\usr\bin\gpg.exe。
配置 GPG 代理以缓存密码（可选）
为了避免每次签名提交时重复输入密码，可以启用 gpg-agent 缓存。编辑 ~/.gnupg/gpg-agent.conf，添加：
default-cache-ttl 3600
max-cache-ttl 86400
重启代理：gpgconf --kill gpg-agent，下次使用时自动启动。
进行签名提交
一切配置就绪后，正常使用 Git 进行提交，签名将自动附加。
git add .
git commit -m "docs: add GPG signing guide"
若启用了 commit.gpgsign，无需额外参数。如果仅临时需要签名使用 -S。
签名标签
除了提交，你还可以为标签签名：
git tag -s v1.0.0 -m "Release version 1.0.0"
这会产生一个带有 GPG 签名的附注标签，在平台上也显示“已验证”。
在 GitHub/GitLab 上添加公钥
只有将公钥上传到你的代码托管平台，平台才能验证你的签名并显示“Verified”标记。
导出公钥
gpg --armor --export ABCDEF1234567890
将输出以 -----BEGIN PGP PUBLIC KEY BLOCK----- 开头的整个文本块复制。
添加到平台
GitHub：
- 登录 → 点击右上角头像 → Settings
- 左侧菜单选择 SSH and GPG keys
- 在 “GPG keys” 旁点击 New GPG key
- 粘贴导出的公钥，保存。
GitLab：
- 登录 → 头像 → Preferences
- 左侧 GPG Keys
- 粘贴公钥，填写标题，保存。
验证提交签名
在本地可以使用 git log 查看提交签名状态：
git log --show-signature
签名有效的提交会显示：
commit 1a2b3c... (HEAD -> main)
gpg: Signature made 2025-03-20 15:30:00 CST
gpg: using RSA key ABCDEF1234567890
gpg: Good signature from "Zhang San <zhangsan@example.com>" [ultimate]
远程仓库中，如果公钥已上传，推送后即可看到绿色的“Verified”标签。
常见问题与故障排除
签名失败：gpg: signing failed: Inappropriate ioctl for device
这通常发生在缺少图形终端的环境（如 SSH 会话或某些容器内）。解决方法：设置 GPG TTY 环境变量，并允许在终端提示输入密码。
在 ~/.bashrc 或 ~/.zshrc 中添加：
export GPG_TTY=$(tty)
然后重新加载配置文件，或者重新登录。
密钥未被信任为“终极信任”
即使签名有效，有时仍显示为 Good signature 但带有警告。你需要对密钥设置信任等级：
gpg --edit-key ABCDEF1234567890
在 gpg 交互命令行输入 trust，选择 5（我绝对信任），然后确认并退出。
提交仍然显示“Unverified”
- 检查
git config user.email与 GPG 密钥中的邮箱是否完全一致。 - 确认已将 公钥 上传到对应平台。
- 检查密钥是否已过期或被撤销。
临时禁用签名
如果你需要在某个仓库中临时关闭强制签名，可在该仓库内执行：
git config commit.gpgsign false