Saltar al contenido principal

Configuración GPG — Firma de commits y tags

En Wiedii todos los commits y tags deben estar firmados con GPG. GitLab CE muestra el badge ✅ Verified en cada commit firmado con una clave registrada en tu perfil, lo que garantiza que el commit lo hizo realmente quien dice haberlo hecho.

Por qué firmamos con GPG​

Sin firma GPG, cualquiera puede hacer un commit con user.name y user.email ajenos — git no verifica identidad. Con commit.gpgsign=true, cada commit lleva una firma criptográfica que solo puede producir quien tenga la clave privada.

Requisitos previos​

# gnupg — el motor GPG
# pinentry-mac — permite ingresar la passphrase en un diálogo nativo de macOS
brew install gnupg pinentry-mac

1. Generar una clave GPG​

gpg --full-generate-key

Cuando pregunte:

PreguntaRespuesta recomendada
Tipo de clave(1) RSA y RSA
Tamaño4096
Caducidad2y (2 años — renovar antes de que expire)
NombreTu nombre completo (ej. Duban Garcia)
EmailTu email Wiedii (xxx@wiedii.co) — debe coincidir con user.email en git
ComentarioDejar vacío o poner Wiedii
PassphraseUna passphrase segura — la necesitarás para firmar

2. Obtener el ID de tu clave​

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

Salida de ejemplo:

sec   rsa4096/DC93325FC4CA40BE 2024-01-15 [SC] [expires: 2026-01-15]
      ABCD1234EFGH5678IJKL9012DC93325FC4CA40BE
uid                 [ultimate] Duban Garcia <duban.garcia@wiedii.co>
ssb   rsa4096/A1B2C3D4E5F60789 2024-01-15 [E]

El ID es la parte después de rsa4096/ en la línea sec: en este ejemplo DC93325FC4CA40BE.

3. Registrar la clave en git​

git config --global user.signingkey DC93325FC4CA40BE   # ← tu ID

Verificar:

git config --global user.signingkey   # → debe imprimir tu ID

4. Configurar el agente GPG para macOS​

El agente GPG recuerda tu passphrase durante la sesión para no pedirla en cada commit. pinentry-mac es el programa que muestra el diálogo nativo de macOS para ingresar la passphrase — es obligatorio para que GPG pueda desbloquear tu clave privada al firmar.

Crea o edita ~/.gnupg/gpg-agent.conf:

mkdir -p ~/.gnupg
chmod 700 ~/.gnupg

Detecta la ruta de pinentry-mac según tu hardware:

which pinentry-mac
# Apple Silicon (M1/M2/M3/M4) → /opt/homebrew/bin/pinentry-mac
# Intel                        → /usr/local/bin/pinentry-mac

Crea el archivo con la ruta correcta para tu Mac:

# Apple Silicon — reemplaza la ruta si tienes Intel
cat > ~/.gnupg/gpg-agent.conf << 'EOF'
# Optimized configuration for macOS and devcontainer
pinentry-program /opt/homebrew/bin/pinentry-mac   # Intel: /usr/local/bin/pinentry-mac
use-standard-socket
allow-loopback-pinentry
default-cache-ttl 28800
max-cache-ttl 86400
EOF
DirectivaFunción
pinentry-programPrograma que muestra el diálogo de passphrase en macOS — obligatorio
use-standard-socketUsa el socket estándar de gpg-agent — mejora compatibilidad con herramientas modernas
allow-loopback-pinentryPermite ingresar la passphrase en terminal puro y devcontainers sin GUI
default-cache-ttl 28800Recuerda la passphrase 8 horas tras el último uso
max-cache-ttl 86400Máximo 24 horas en caché aunque se siga usando

Recarga el agente:

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

5. Añadir la variable de entorno al .zshrc​

Abre ~/.zshrc y asegúrate de que existe esta línea (normalmente ya la añade Starship o el propio gpg):

export GPG_TTY=$(tty)

Si no está, añádela antes del bloque de mise shims. Recarga el shell para que tome efecto:

exec zsh   # aplica el cambio en el terminal actual
# Si tienes más terminales o sesiones SSH abiertas, ejecuta exec zsh en cada una

6. Exportar la clave pública y añadirla a GitLab​

gpg --armor --export DC93325FC4CA40BE   # ← tu ID

Copia toda la salida (desde -----BEGIN PGP PUBLIC KEY BLOCK----- hasta -----END PGP PUBLIC KEY BLOCK-----).

En GitLab CE (gitlab.wiedii.co):

  1. Ve a tu perfil → Preferences → GPG Keys
  2. Pega la clave pública
  3. Haz clic en Add key

7. Verificar que funciona​

# Hacer un commit de prueba y verificar la firma
echo "gpg test" >> /tmp/test-gpg.txt
cd /tmp && git init test-gpg && cd test-gpg
git commit --allow-empty -m "test: verificar firma GPG"
git log --show-signature -1

Deberías ver algo como:

gpg: Signature made ...
gpg: Good signature from "Duban Garcia <duban.garcia@wiedii.co>"

En GitLab, los commits firmados aparecen con el badge Verified junto al hash del commit.

8. Renovar la clave antes de que expire​

Las claves tienen caducidad de 2 años. Para extender sin perder el historial verificado:

gpg --edit-key DC93325FC4CA40BE
# En el prompt de gpg:
gpg> expire
# Seleccionar nueva fecha (ej. 2y)
gpg> save

Luego volver a exportar y actualizar en GitLab (pasos 6 y 7).

Solución de problemas frecuentes​

error: gpg failed to sign the data​

export GPG_TTY=$(tty)
gpgconf --kill gpg-agent
gpgconf --launch gpg-agent

Si persiste, verificar que pinentry-mac está instalado y la ruta coincide con la del gpg-agent.conf:

which pinentry-mac
# Apple Silicon → /opt/homebrew/bin/pinentry-mac
# Intel         → /usr/local/bin/pinentry-mac

La passphrase se pide en cada commit​

Verificar que ~/.gnupg/gpg-agent.conf tiene pinentry-program apuntando a la ruta correcta de pinentry-mac (ver paso 4), que default-cache-ttl tiene un valor razonable (ej. 28800), y que GPG_TTY está exportado.

GitLab no muestra "Verified"​

  • El email de la clave GPG debe coincidir exactamente con user.email en git y con el email principal de tu cuenta GitLab.
  • La clave debe estar activa (no expirada) en el momento del commit.
  • La clave pública debe estar añadida en GitLab → Preferences → GPG Keys.

Warp terminal no muestra el diálogo de passphrase​

Warp a veces intercepta TTY. Añadir al .zshrc:

if [[ "$IS_WARP" == "true" ]]; then
  export GPG_TTY=$(tty)
fi

Luego recargar: exec zsh (y en cada terminal abierta donde quieras que aplique).

Resumen de comandos clave​

# Ver claves disponibles
gpg --list-secret-keys --keyid-format=long

# Exportar clave pública (para GitLab)
gpg --armor --export <KEY_ID>

# Verificar firma del último commit
git log --show-signature -1

# Matar y relanzar el agente GPG
gpgconf --kill gpg-agent && gpgconf --launch gpg-agent

Referencias​