Saltar al contenido principal

Configuración de llaves GPG

Esta guía te mostrará cómo generar, configurar y usar llaves GPG para firmar tus commits y tags en Git.

Prerrequisitos​

Antes de comenzar, asegúrate de:

  1. Tener tu email verificado en GitHub
  2. Usar el email correcto (el mismo que tienes en GitHub)

Instalación de GPG​

En macOS:​

# Con Homebrew
brew install gnupg

# Verificar instalación
gpg --version

En Linux (Ubuntu/Debian):​

# Instalar GPG
sudo apt update
sudo apt install gnupg

# Verificar instalación
gpg --version

En Windows:​

  1. Descarga GPG4Win desde gpg4win.org
  2. Instala siguiendo las instrucciones
  3. Usa Git Bash para los comandos

Generar una nueva llave GPG​

Paso 1: Verificar llaves existentes​

Primero, verifica si ya tienes llaves GPG:

gpg --list-secret-keys --keyid-format=long

Si no ves ninguna llave o quieres crear una nueva, continúa.

Paso 2: Generar la llave​

Para GPG 2.1.17 o superior (recomendado):​

gpg --full-generate-key

Para versiones anteriores:​

gpg --default-new-key-algo rsa4096 --gen-key

Paso 3: Configurar los parámetros​

Durante el proceso te preguntará:

  1. Tipo de llave: Presiona Enter para RSA (predeterminado)
  2. Tamaño de llave: Ingresa 4096 para mayor seguridad
  3. Información personal:
    • Nombre real: Tu nombre completo
    • Email: DEBE ser el mismo email verificado en GitHub
    • Comentario: Opcional (ej: "Trabajo", "Personal")
  4. Passphrase: Ingresa una contraseña segura

Is this correct? (y/N) y

Real name: John Doe Email address: john.doe@example.com


## Configurar Git para usar GPG

### Paso 1: Obtener el ID de tu llave

```bash
gpg --list-secret-keys --keyid-format=long

Busca una línea similar a esta:

sec   rsa4096/3AA5C34371567BD2 2016-03-10 [SC] [expires: 2026-03-10]

El ID de la llave es 3AA5C34371567BD2 (después de rsa4096/).

Paso 2: Configurar Git globalmente​

# Configurar GPG para firmar commits
git config --global user.signingkey 3AA5C34371567BD2

# Configurar para firmar todos los commits automáticamente
git config --global commit.gpgsign true

# Configurar para firmar todos los tags automáticamente
git config --global tag.gpgsign true

# Configurar el programa GPG (si es necesario en Linux)
git config --global gpg.program gpg
info

Si tienes un perfil de git coloca la configuración en tu git profile.

Paso 3: Configurar para proyectos específicos (opcional)​

Si solo quieres firmar commits en ciertos proyectos:

# En el directorio del proyecto
git config user.signingkey 3AA5C34371567BD2
git config commit.gpgsign true
git config tag.gpgsign true

Agregar llave GPG a GitHub​

Paso 1: Exportar tu llave pública​

gpg --armor --export 3AA5C34371567BD2

Esto mostrará algo como:

-----BEGIN PGP PUBLIC KEY BLOCK-----

mQINBFc...
...
...
=abCD
-----END PGP PUBLIC KEY BLOCK-----

Copia todo el contenido, incluyendo las líneas -----BEGIN...----- y -----END...-----.

Paso 2: Agregar en GitHub​

  1. Ve a GitHub.com e inicia sesión
  2. Configuración:
    • Haz clic en tu foto de perfil → "Settings"
  3. SSH and GPG keys:
    • En la barra lateral → "SSH and GPG keys"
  4. Nueva llave GPG:
    • Haz clic en "New GPG key"
  5. Agregar información:
    • Title: Nombre descriptivo (ej: "MacBook Pro - GPG")
    • Key: Pega la llave pública copiada
  6. Guardar:
    • Haz clic en "Add GPG key"
    • Confirma con tu contraseña de GitHub

Paso 3: Verificar configuración​

Crea un commit de prueba:

# Hacer un cambio
echo "Test GPG signing" >> test.txt
git add test.txt
git commit -m "Test: verificar firma GPG"

El commit debe mostrar "Verified" 🟢 en GitHub.

Configuraciones Avanzadas​

Configurar GPG Agent (para evitar ingresar passphrase constantemente)​

En macOS:​

# Agregar al ~/.zshrc o ~/.bash_profile
echo 'export GPG_TTY=$(tty)' >> ~/.zshrc
source ~/.zshrc

En Linux:​

# Agregar al ~/.bashrc o ~/.zshrc
echo 'export GPG_TTY=$(tty)' >> ~/.bashrc
echo 'if [ -r ~/.gnupg/.gpg-agent-info ]; then' >> ~/.bashrc
echo '  . ~/.gnupg/.gpg-agent-info' >> ~/.bashrc
echo '  export GPG_AGENT_INFO' >> ~/.bashrc
echo 'fi' >> ~/.bashrc
source ~/.bashrc

Configurar tiempo de cache de passphrase​

Edita ~/.gnupg/gpg-agent.conf:

# Tiempo en cache (en segundos)
default-cache-ttl 28800        # 8 horas
max-cache-ttl 86400           # 24 horas

Luego reinicia el agente:

gpgconf --reload gpg-agent

Usar GitHub CLI (Alternativa rápida)​

Si tienes GitHub CLI instalado:

# Instalar GitHub CLI (macOS)
brew install gh

# Autenticar
gh auth login

# Agregar llave GPG
gh gpg-key add ~/.gnupg/exported-gpg-key.asc

Comandos Útiles​

Gestión de llaves:​

# Listar llaves públicas
gpg --list-keys

# Listar llaves privadas
gpg --list-secret-keys

# Exportar llave pública
gpg --armor --export KEY_ID

# Exportar llave privada (backup)
gpg --armor --export-secret-keys KEY_ID

# Eliminar llave
gpg --delete-secret-keys KEY_ID
gpg --delete-keys KEY_ID

Firma manual de commits:​

# Firmar un commit específico
git commit -S -m "Commit firmado manualmente"

# Verificar firmas localmente
git log --show-signature

Troubleshooting Común​

Error: "gpg: signing failed: Inappropriate ioctl for device"​

export GPG_TTY=$(tty)

Error: "gpg: signing failed: No secret key"​

Verifica que el key ID esté configurado correctamente:

git config --global user.signingkey
gpg --list-secret-keys --keyid-format=long

Error: "gpg: can't connect to the agent"​

Reinicia el GPG agent:

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

Commits no aparecen como "Verified" en GitHub​

  1. Email no coincide: Verifica que el email en GPG sea el mismo que en GitHub
  2. Llave no agregada: Asegúrate de haber agregado la llave pública a GitHub
  3. Email no verificado: El email debe estar verificado en tu cuenta GitHub

Renovar llave expirada​

# Listar llaves
gpg --list-keys

# Editar llave (cambia KEY_ID por tu ID)
gpg --edit-key KEY_ID

# En el prompt de GPG:
expire
# Selecciona nueva fecha de expiración
save

Buenas Prácticas​

🔒 Seguridad​

  • Usa passphrase fuerte para tu llave privada
  • Haz backup seguro de tus llaves privadas
  • Revoca llaves comprometidas inmediatamente

📁 Organización​

  • Una llave por dispositivo/propósito (trabajo, personal)
  • Nombres descriptivos al agregarlas a GitHub
  • Documenta tus llaves y fechas de expiración

🔄 Mantenimiento​

  • Renueva antes de expirar
  • Actualiza GitHub con nuevas llaves
  • Limpia llaves viejas del sistema
aviso

Backup importante: Haz backup de tu llave privada y passphrase en un lugar seguro. Si pierdes acceso, no podrás firmar commits con esa identidad.

tip

Tip: Configura commit.gpgsign = true globalmente solo si siempre quieres firmar. Para proyectos específicos, configúralo por repositorio o directorio de trabajo.