gpg-signing

What this skill does

# Git GPG Signing

Comprehensive guidance for setting up, configuring, and troubleshooting GPG commit signing across all platforms.

## Table of Contents

- [Overview](#overview)
- [When to Use This Skill](#when-to-use-this-skill)
- [Quick Start](#quick-start)
- [Platform-Specific Setup](#platform-specific-setup)
- [Key Generation](#key-generation)
- [Git Configuration](#git-configuration)
- [Passphrase Caching](#passphrase-caching)
- [GitHub Integration](#github-integration)
- [Troubleshooting](#troubleshooting)
- [GPG Signing Methods Comparison](#gpg-signing-methods-comparison)
- [Security Best Practices](#security-best-practices)
- [Resources](#resources)
- [Related Skills](#related-skills)

## Overview

Git commit signing provides cryptographic proof that commits came from you. This skill helps you:

- Install and configure GPG tools on Windows, macOS, and Linux
- Set up commit signing with proper key management
- Configure passphrase caching for better workflow
- Troubleshoot common GPG signing issues
- Understand security trade-offs and best practices

## When to Use This Skill

This skill should be used when:

- Setting up GPG commit signing for the first time
- Configuring GPG tools (Gpg4win, GPG Suite, gnupg)
- Troubleshooting GPG signing errors ("gpg: signing failed", "inappropriate ioctl", etc.)
- Troubleshooting keyboxd daemon startup issues (Windows race condition)
- Determining which GPG installation Git is using
- Understanding Windows daemon startup behavior vs. official design
- Configuring passphrase caching to reduce prompts
- Understanding GPG vs SSH vs S/MIME signing methods
- Adding GPG keys to GitHub/GitLab/Bitbucket
- Resolving "Unverified" commits on GitHub
- Working with `.gnupg/gpg-agent.conf` configuration

## Quick Start

**Basic Setup (Single Personal Key):**

```bash
# 1. Install GPG (see Platform-Specific Setup below)

# 2. Generate key
gpg --full-generate-key
# Select: (9) ECC (sign and encrypt) → Curve 25519
# Expiration: 0 (no expiration)
# Passphrase: Strong 20+ character passphrase

# 3. Get key ID
gpg --list-secret-keys --keyid-format=long
# Look for "sec   ed25519/<KEY_ID>"

# 4. Configure Git
git config --global user.signingkey <KEY_ID>
git config --global commit.gpgsign true

# 5. Export public key and add to GitHub
gpg --armor --export <KEY_ID>
# Paste at: https://github.com/settings/keys
```

## Platform-Specific Setup

### Windows: Gpg4win Installation

**For detailed Windows setup**, see [references/windows-setup.md](references/windows-setup.md).

**Quick install:**

```powershell
# Option 1: Download installer
# https://gpg4win.org/thanks-for-download.html

# Option 2: winget
winget install --id GnuPG.Gpg4win -e --source winget

# Configure Git to use Gpg4win (adjust path if installed elsewhere)
git config --global gpg.program "C:/Program Files (x86)/GnuPG/bin/gpg.exe"
```

### macOS: GPG Suite / Homebrew

```bash
# Option 1: Homebrew (recommended)
brew install gnupg

# Option 2: GPG Suite
# Download from: https://gpgtools.org/

# Configure Git (if needed)
git config --global gpg.program $(which gpg)
```

### Linux: GnuPG

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

# Fedora/RHEL
sudo dnf install gnupg2

# Arch
sudo pacman -S gnupg
```

### WSL: Follow Linux Instructions

**WSL users:** Follow the Linux setup instructions above (WSL runs Linux). See troubleshooting section for WSL-specific issues if needed.

## Key Generation

### Personal Development Key (Interactive)

```bash
# Generate key interactively
gpg --full-generate-key

# Follow prompts:
# 1. Key type: (9) ECC (sign and encrypt) *default*
# 2. Curve: (1) Curve 25519 *default*
# 3. Expiration: 0 = no expiration (or 2y for 2 years)
# 4. Real name: Your Name
# 5. Email: [email protected]
# 6. Comment: (optional, can leave blank)
# 7. Passphrase: Strong 20+ character passphrase

# List keys to get KEY_ID
gpg --list-secret-keys --keyid-format=long
# Look for "sec   ed25519/<KEY_ID>"
```

**Recommended algorithm:** EdDSA using Curve25519 (Ed25519) - modern, fast, small keys, excellent security

**Alternative:** RSA 4096-bit (traditional, widely compatible)

### Exporting Keys

```bash
# Export public key (for GitHub)
gpg --armor --export <KEY_ID>

# Export private key (for backup only - KEEP SECURE!)
gpg --armor --export-secret-keys <KEY_ID>
```

## Git Configuration

### Enable Commit Signing

```bash
# Global (all repositories)
git config --global user.signingkey <KEY_ID>
git config --global commit.gpgsign true
git config --global tag.gpgSign true

# Repository-local (specific repo)
cd /path/to/repo
git config user.signingkey <KEY_ID>
git config commit.gpgsign true
```

### Verify Configuration

```bash
# Check configured key
git config --global user.signingkey

# Test signing
git commit --allow-empty -m "Test GPG signing"

# Verify signature
git log --show-signature -1
```

## Passphrase Caching

GPG agent caches passphrases to reduce how often you're prompted.

**Check if config exists:**

```bash
ls ~/.gnupg/gpg-agent.conf
```

**Create or edit** `~/.gnupg/gpg-agent.conf`:

```conf
# Cache passphrase for 8 hours of inactivity
default-cache-ttl 28800

# Maximum cache time of 24 hours regardless of use
max-cache-ttl 86400

# Allow pinentry to cache the passphrase
allow-preset-passphrase
```

**Apply changes:**

```bash
gpgconf --kill gpg-agent
gpgconf --launch gpg-agent
```

**For comprehensive caching configuration**, including security scenarios, testing procedures, and troubleshooting, see [references/passphrase-caching.md](references/passphrase-caching.md).

### Windows-Specific: Dual GPG Installation Issue

**CRITICAL for Windows users:** Windows typically has **two separate GPG installations** (Gpg4win and Git Bash GPG), each with different config file locations:

- **Gpg4win:** `%APPDATA%\gnupg\gpg-agent.conf` (typically `C:\Users\<Username>\AppData\Roaming\gnupg\gpg-agent.conf`)
- **Git Bash GPG:** `~/.gnupg/gpg-agent.conf` (resolves to `C:\Users\<Username>\.gnupg\gpg-agent.conf`)

**Common problem:** Configuring `~/.gnupg/gpg-agent.conf` (Git Bash GPG) when Git is configured to use Gpg4win. Result: **configuration silently ignored, caching doesn't work**.

**Verify which GPG Git is using:**

```bash
# Check Git's GPG configuration
git config --global gpg.program

# If output is "C:/Program Files (x86)/GnuPG/bin/gpg.exe":
# → Use: %APPDATA%\gnupg\gpg-agent.conf

# Verify GPG's config directory
gpgconf --list-dirs homedir
```

**Windows configuration must include pinentry-program:**

```conf
# Example: %APPDATA%\gnupg\gpg-agent.conf
default-cache-ttl 28800
max-cache-ttl 86400
allow-preset-passphrase

# REQUIRED for Windows:
pinentry-program C:/Program Files (x86)/GnuPG/bin/pinentry-basic.exe
```

**See:** [Windows Setup Guide - Dual GPG Installations](references/windows-setup.md) for detailed explanation.

### Recommended Cache Durations

| Scenario | default-cache-ttl | max-cache-ttl | Rationale |
| --- | --- | --- | --- |
| **High Security** | 900 (15 min) | 3600 (1 hour) | Prompt frequently, short window |
| **Balanced** | 3600 (1 hour) | 28800 (8 hours) | Prompt every ~hour, expires by end of day |
| **Convenience** | 28800 (8 hours) | 86400 (24 hours) | Prompt once per workday, expires daily |

## GitHub Integration

### Adding GPG Key to GitHub

1. **Export public key:**

   ```bash
   gpg --armor --export <KEY_ID>
   ```

2. **Add to GitHub:**
   - Go to: [https://github.com/settings/keys](https://github.com/settings/keys)
   - Click "New GPG key"
   - Paste ASCII-armored public key
   - Click "Add GPG key"

3. **Verify email matches:**
   - Git email must match GPG key email
   - Email must be verified in GitHub account

   ```bash
   # Check Git email
   git config --global user.email

   # Check GPG key email
   gpg --list-keys <KEY_ID>
   ```

### Troubleshooting "Unverified" Commits

**Possible causes:**

1. **Public key not added to GitHub** → Add key at Settings → SSH and GPG keys
2. **Email mis