⚡

GitGPG签名Skill gpg-signing

本技能提供全面的GPG提交签名指南，帮助用户在Windows、macOS、Linux等多平台上设置、配置和故障排除GPG工具，确保代码提交的安全性和可验证性。涵盖密钥生成、Git配置、密码缓存、GitHub集成和常见问题解决，并遵循安全最佳实践。适用于开发者和DevOps工程师，优化开发工作流。关键词：GPG, Git, 提交签名, 密钥管理, 故障排除, 安全, 多平台, DevOps。

DevOps 0 次安装 0 次浏览 更新于 3/11/2026

名称: gpg-签名 描述: GPG提交签名的全面指南。设置、配置和故障排除GPG提交签名。修复GPG签名错误，配置密码缓存，验证提交签名。适用于处理Git提交签名、GPG密钥、提交验证、签名验证、GPG配置或遇到GPG签名错误时。涵盖Windows（Gpg4win）、macOS（GPG Suite）、Linux（gnupg）和WSL安装和设置。 允许工具: Read, Bash, Glob, Grep

Git GPG 签名

为所有平台提供设置、配置和故障排除GPG提交签名的全面指导。

目录

概述

Git提交签名提供加密证明，表明提交来自您。此技能帮助您：

  • 在Windows、macOS和Linux上安装和配置GPG工具
  • 使用正确的密钥管理设置提交签名
  • 配置密码缓存以优化工作流程
  • 故障排除常见GPG签名问题
  • 理解安全权衡和最佳实践

何时使用此技能

此技能应在以下情况下使用：

  • 首次设置GPG提交签名
  • 配置GPG工具（Gpg4win、GPG Suite、gnupg）
  • 故障排除GPG签名错误（“gpg: signing failed”、“inappropriate ioctl”等）
  • 故障排除keyboxd守护进程启动问题（Windows竞争条件）
  • 确定Git正在使用哪个GPG安装
  • 理解Windows守护进程启动行为与官方设计
  • 配置密码缓存以减少提示
  • 理解GPG vs SSH vs S/MIME签名方法
  • 将GPG密钥添加到GitHub/GitLab/Bitbucket
  • 解决GitHub上的“未验证”提交
  • 处理.gnupg/gpg-agent.conf配置

快速开始

基本设置（单个个人密钥）：

# 1. 安装GPG（见下方平台特定设置）

# 2. 生成密钥
gpg --full-generate-key
# 选择：(9) ECC（签名和加密）→ Curve 25519
# 过期时间：0（无过期）
# 密码：强20+字符密码

# 3. 获取密钥ID
gpg --list-secret-keys --keyid-format=long
# 查找“sec   ed25519/<密钥ID>”

# 4. 配置Git
git config --global user.signingkey <密钥ID>
git config --global commit.gpgsign true

# 5. 导出公钥并添加到GitHub
gpg --armor --export <密钥ID>
# 粘贴到：https://github.com/settings/keys

平台特定设置

Windows：Gpg4win 安装

详细Windows设置，见参考资料/windows-setup.md。

快速安装：

# 选项1：下载安装程序
# https://gpg4win.org/thanks-for-download.html

# 选项2：winget
winget install --id GnuPG.Gpg4win -e --source winget

# 配置Git使用Gpg4win（如果安装在其他路径，请调整）
git config --global gpg.program "C:/Program Files (x86)/GnuPG/bin/gpg.exe"

macOS：GPG Suite / Homebrew

# 选项1：Homebrew（推荐）
brew install gnupg

# 选项2：GPG Suite
# 下载自：https://gpgtools.org/

# 配置Git（如果需要）
git config --global gpg.program $(which gpg)

Linux：GnuPG

# Debian/Ubuntu
sudo apt update && sudo apt install gnupg

# Fedora/RHEL
sudo dnf install gnupg2

# Arch
sudo pacman -S gnupg

WSL：遵循Linux说明

WSL用户： 遵循上述Linux设置说明（WSL运行Linux）。如果需要，见故障排除部分以了解WSL特定问题。

密钥生成

个人开发密钥（交互式）

# 交互式生成密钥
gpg --full-generate-key

# 按照提示：
# 1. 密钥类型：(9) ECC（签名和加密）*默认*
# 2. 曲线：(1) Curve 25519 *默认*
# 3. 过期时间：0 = 无过期（或2y表示2年）
# 4. 真实姓名：您的姓名
# 5. 邮箱：您的验证邮箱@email.com
# 6. 评论：（可选，可留空）
# 7. 密码：强20+字符密码

# 列出密钥以获取密钥ID
gpg --list-secret-keys --keyid-format=long
# 查找“sec   ed25519/<密钥ID>”

推荐算法： 使用Curve25519的EdDSA（Ed25519）— 现代、快速、密钥小、安全性优秀

替代： RSA 4096位（传统，兼容性广）

导出密钥

# 导出公钥（用于GitHub）
gpg --armor --export <密钥ID>

# 导出私钥（仅用于备份 — 保持安全！）
gpg --armor --export-secret-keys <密钥ID>

Git 配置

启用提交签名

# 全局（所有仓库）
git config --global user.signingkey <密钥ID>
git config --global commit.gpgsign true
git config --global tag.gpgSign true

# 仓库本地（特定仓库）
cd /path/to/repo
git config user.signingkey <密钥ID>
git config commit.gpgsign true

验证配置

# 检查配置的密钥
git config --global user.signingkey

# 测试签名
git commit --allow-empty -m "测试GPG签名"

# 验证签名
git log --show-signature -1

密码缓存

GPG代理缓存密码以减少提示频率。

检查配置是否存在：

ls ~/.gnupg/gpg-agent.conf

创建或编辑 ~/.gnupg/gpg-agent.conf：

# 缓存密码，在8小时不活动后失效
default-cache-ttl 28800

# 无论使用情况，最大缓存时间为24小时
max-cache-ttl 86400

# 允许pinentry缓存密码
allow-preset-passphrase

应用更改：

gpgconf --kill gpg-agent
gpgconf --launch gpg-agent

全面缓存配置，包括安全场景、测试程序和故障排除，见参考资料/passphrase-caching.md。

Windows特定：双重GPG安装问题

Windows用户关键： Windows通常有两个独立的GPG安装（Gpg4win和Git Bash GPG），每个有不同的配置文件位置：

  • Gpg4win： %APPDATA%\gnupg\gpg-agent.conf（通常 C:\Users\<用户名>\AppData\Roaming\gnupg\gpg-agent.conf）
  • Git Bash GPG： ~/.gnupg/gpg-agent.conf（解析为 C:\Users\<用户名>\.gnupg\gpg-agent.conf）

常见问题： 当Git配置为使用Gpg4win时，配置了~/.gnupg/gpg-agent.conf（Git Bash GPG）。结果：配置被静默忽略，缓存不工作。

验证Git正在使用哪个GPG：

# 检查Git的GPG配置
git config --global gpg.program

# 如果输出是“C:/Program Files (x86)/GnuPG/bin/gpg.exe”：
# → 使用：%APPDATA%\gnupg\gpg-agent.conf

# 验证GPG的配置目录
gpgconf --list-dirs homedir

Windows配置必须包含pinentry-program：

# 示例：%APPDATA%\gnupg\gpg-agent.conf
default-cache-ttl 28800
max-cache-ttl 86400
allow-preset-passphrase

# Windows必需：
pinentry-program C:/Program Files (x86)/GnuPG/bin/pinentry-basic.exe

见： Windows设置指南 — 双重GPG安装以获取详细解释。

推荐缓存持续时间

场景 default-cache-ttl max-cache-ttl 理由
高安全性 900（15分钟） 3600（1小时） 频繁提示，短窗口
平衡 3600（1小时） 28800（8小时） 每小时提示一次，当天过期
便利性 28800（8小时） 86400（24小时） 每个工作日提示一次，每天过期

GitHub 集成

添加GPG密钥到GitHub

  1. 导出公钥：

    gpg --armor --export <密钥ID>

  2. 添加到GitHub：

  3. 验证邮箱匹配：

    • Git邮箱必须匹配GPG密钥邮箱
    • 邮箱必须在GitHub账户中验证
    # 检查Git邮箱
git config --global user.email

# 检查GPG密钥邮箱
gpg --list-keys <密钥ID>

故障排除“未验证”提交

可能原因：

  1. 公钥未添加到GitHub → 在设置 → SSH和GPG密钥中添加密钥
  2. 邮箱不匹配 → 确保Git邮箱 = GPG密钥邮箱 = GitHub验证邮箱
  3. 密钥过期 → 延长过期时间或生成新密钥
  4. 密钥吊销 → 生成新密钥（无法撤销）

故障排除

全面故障排除，见参考资料/troubleshooting.md。

“gpg: signing failed: No secret key”

原因： Git配置为使用密钥ID，但密钥环中不存在。

解决方案：

# 列出可用密钥
gpg --list-secret-keys --keyid-format=long

# 验证Git配置匹配可用密钥
git config --global user.signingkey

# 如果不匹配，更新配置
git config --global user.signingkey <正确密钥ID>

“gpg: signing failed: Inappropriate ioctl for device”

原因： GPG代理无法提示输入密码（终端问题）。

解决方案（Linux/macOS/WSL）：

# 设置GPG_TTY环境变量
export GPG_TTY=$(tty)

# 添加到shell配置文件（例如，~/.bashrc、~/.zshrc）
echo 'export GPG_TTY=$(tty)' >> ~/.bashrc

解决方案（Windows with Gpg4win）：

# 使用GUI pinentry（调整路径以匹配您的Gpg4win安装）
echo 'pinentry-program "C:/Program Files (x86)/GnuPG/bin/pinentry-basic.exe"' >> ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent

“error: gpg failed to sign the data”

调试步骤：

# 直接测试GPG签名
echo "test" | gpg --clearsign

# 检查GPG代理状态
gpgconf --list-components

# 检查密钥过期时间
gpg --list-keys --keyid-format=long <密钥ID>

# 重启GPG代理
gpgconf --kill gpg-agent
gpgconf --launch gpg-agent

# 再次尝试提交
git commit -m "test"

每次提交都提示密码（缓存不工作）

Windows用户： 这通常由双重GPG安装问题引起。见Windows设置 — 密码缓存故障排除和故障排除 — Windows缓存问题以获取详细诊断。

可能原因：

  1. 错误的配置文件位置（Windows）：

    # 验证Git正在使用哪个GPG
git config --global gpg.program

# 检查GPG的配置目录

gpgconf --list-dirs homedir

确保配置存在于正确位置

Windows（Gpg4win）：%APPDATA%\gnupg\gpg-agent.conf

Windows（Git Bash）：~/.gnupg/gpg-agent.conf

Linux/macOS/WSL：~/.gnupg/gpg-agent.conf


2. **gpg-agent.conf未加载：**

```bash
# 重启代理以加载配置
gpgconf --kill gpg-agent
gpgconf --launch gpg-agent

# 验证配置已加载
gpgconf --list-options gpg-agent | grep cache-ttl

  1. 缓存TTL设置过低 → 在~/.gnupg/gpg-agent.conf中增加缓存时间

  2. 多个GPG代理运行：

    # 杀死所有代理
pkill gpg-agent

# 启动单个代理
gpgconf --launch gpg-agent

GPG 签名方法比较

方法 最适合 设置复杂性 密钥管理
GPG 全功能，支持过期/吊销 中等 最灵活
SSH 最简单，重用现有SSH密钥 低 功能有限
S/MIME 具有X.509证书的企业 高 组织管理

SSH签名（替代）

何时使用SSH代替GPG：

  • 简单的个人项目
  • 已有SSH密钥设置
  • 不需要过期/吊销功能
  • 想要最小配置

设置：

# 配置Git使用SSH签名
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

# 将SSH密钥添加到GitHub作为“Signing Key”

限制：

  • 无密钥过期支持
  • 无吊销跟踪
  • 需要Git 2.34+（2021）

安全最佳实践

全面安全指导，见参考资料/security-best-practices.md。

快速推荐：

  • ✅ 对个人密钥使用密码保护（最少20字符）
  • ✅ 配置缓存以平衡安全性和便利性（4-8小时）
  • ✅ 考虑密钥过期：个人项目无过期，企业工作1年过期
  • ✅ 备份私钥到加密保险库或密码管理器的安全文档
  • ⚠️ 永远不要在Git仓库、云存储或电子邮件中存储未加密密钥

资源

参考资料

官方文档

相关技能

  • git-commit：使用完整的git提交工作流程，包括Conventional Commits格式、安全协议和归属要求
  • git-identity：使用多身份GPG密钥隔离 — 使用includeIf条件包含将不同的GPG密钥范围限定到不同目录
  • config：高级Git配置，包括别名、凭证和性能调优
  • setup：Git安装和配置的先决条件

版本历史

  • v1.1.1（2025-11-25）：渐进披露优化 — 将测试场景提取到参考文件，移除冗余快速命令参考部分，减少SKILL.md至500行以下
  • v1.1.0（2025-11-22）：增强故障排除 — 添加keyboxd守护进程竞争条件故障排除（T7777/T7829），动态GPG检测工作流程，Windows启动最佳实践与官方设计vs现实分析
  • v1.0.5（2025-11-19）：优化改进 — 向SKILL.md添加目录，将基本命令参考提取到quick-reference.md，行数从530减少到522
  • v1.0.4（2025-11-17）：渐进披露改进 — 将安全最佳实践提取到单独的参考文件
  • v1.0.3（2025-11-17）：基于官方文档验证 — 修复tag.gpgSign大小写，更新Last Verified日期
  • v1.0.2（2025-11-12）：增强文档 — 向长参考添加目录，记录测试场景
  • v1.0.1（2025-11-13）：添加跨引用到git-commit技能
  • v1.0.0（2025-01-09）：初始发布，从仓库文档迁移

最后更新

日期： 2025-11-28 模型： claude-opus-4-5-20251101