devAlice
← Windows

Autenticación Git en Windows — Credential Manager, SSH y firma de commits

Configuración limpia de Git en Windows: Git Credential Manager, claves SSH, firma SSH y múltiples cuentas.

La autenticación Git en Windows es algo más compleja que en macOS/Linux — Git Credential Manager (GCM), OpenSSH y el agente de 1Password pueden colisionar. Esta guía es una configuración inicial limpia que no tendrás que tocar en un año.

Objetivo: Windows 11 + Git for Windows + GitHub (tras la configuración inicial de Windows).

Resumen

  1. Git Credential Manager (GCM) — OAuth (inicio de sesión en el navegador) para clones HTTPS
  2. Claves OpenSSH — para clones SSH. Se recomienda Ed25519
  3. Firma de commits — mediante clave SSH (más sencillo que GPG)
  4. Separación trabajo/personal — Include.path o alias de Host en ~/.ssh/config
  5. Agente SSH de 1Password (opcional) — claves en el vault

Requisitos previos

  • Git for Windows 2.40+ — winget install --id Git.Git (configuración inicial de Windows)
  • Cliente OpenSSH habilitado (predeterminado en Win11) — comprueba con Get-WindowsCapability -Online -Name "OpenSSH.Client*"

1. Git Credential Manager — HTTPS

GCM viene incluido con Git for Windows. Los clones/pushes HTTPS abren el flujo OAuth del navegador automáticamente:

git clone https://github.com/user/repo.git
# El navegador se abre → inicio de sesión en GitHub → token almacenado automáticamente

Almacenamiento: Windows Credential Manager (Panel de control → Cuentas de usuario → Administrador de credenciales → Credenciales de Windows).

Verificación

git config --global credential.helper
# manager

Si aparece manager, GCM está activo. En caso contrario:

git config --global credential.helper manager

Múltiples cuentas (trabajo + GitHub personal)

Diferentes helpers por URL:

git config --global --add credential.https://github.com.useHttpPath true

Ahora hay credenciales separadas por ruta en el mismo host.

2. Claves SSH

SSH es más fluido que HTTPS (sin navegador). Genera una clave Ed25519:

ssh-keygen -t ed25519 -C "tu@ejemplo.com"
# Ruta: ~/.ssh/id_ed25519 (predeterminada)
# Frase de contraseña: recomendada (el agente de 1Password la desbloquea automáticamente)

Mostrar la clave pública:

Get-Content ~/.ssh/id_ed25519.pub
# ssh-ed25519 AAAA... tu@ejemplo.com

GitHub → Settings → SSH and GPG keys → New SSH key → pega la clave pública.

Habilitar ssh-agent (desbloqueo automático de frase de contraseña)

# PowerShell como administrador
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent
 
# PowerShell normal
ssh-add ~/.ssh/id_ed25519
# Introduce la frase una vez; después es automático

Verificar SSH

ssh -T git@github.com
# Hi yourname! You've successfully authenticated, but GitHub does not provide shell access.

Cambiar la URL remota (HTTPS → SSH)

git remote set-url origin git@github.com:user/repo.git

3. Firma de commits con SSH

Más sencillo que GPG y reutiliza la misma clave. Requiere Git 2.34+.

git config --global gpg.format ssh
git config --global user.signingkey "ssh-ed25519 AAAA... tu@ejemplo.com"
git config --global commit.gpgsign true
git config --global tag.gpgsign true

user.signingkey es la línea completa de la clave pública. O una referencia a archivo:

git config --global user.signingkey "C:/Users/me/.ssh/id_ed25519.pub"

Registrar la clave de firma en GitHub

Registra la misma clave pública en GitHub → SSH and GPG keys → Add new SSH key → Key type = Signing Key.

Prueba

git commit --allow-empty -m "test signed"
git log --show-signature -1
# Good "git" signature with ED25519 key SHA256:...

Comprueba la insignia «Verified» en la página del PR.

Archivo allowed_signers (necesario para verificación local)

~/.config/git/allowed_signers:

tu@ejemplo.com ssh-ed25519 AAAA...
compañero@ejemplo.com ssh-ed25519 BBBB...

git config --global gpg.ssh.allowedSignersFile "$HOME/.config/git/allowed_signers"

git log --show-signature verifica ahora también los commits de otros.

4. Múltiples cuentas GitHub (trabajo + personal)

4.1 Configuración SSH — alias de Host

~/.ssh/config:

Host github.com-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_personal
  IdentitiesOnly yes

Host github.com-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work
  IdentitiesOnly yes

Clonar:

git clone git@github.com-personal:personal-user/repo.git
git clone git@github.com-work:company/repo.git

4.2 user.email por carpeta — includeIf

~/.gitconfig:

[user]
    name = Tu Nombre
    email = personal@ejemplo.com
 
[includeIf "gitdir:C:/Users/me/work/"]
    path = C:/Users/me/.gitconfig-work

~/.gitconfig-work:

[user]
    email = yo@empresa.com
    signingkey = ssh-ed25519 AAAA... yo@empresa.com

Los repositorios bajo C:/Users/me/work/ usan automáticamente el email/clave de trabajo.

Verificar:

cd C:\Users\me\work\some-repo
git config user.email
# yo@empresa.com
 
cd C:\Users\me\personal\some-repo
git config user.email
# personal@ejemplo.com

5. Agente SSH de 1Password (opcional)

Consulta gestor de contraseñas. En Windows, configura el socket del agente mediante una variable de entorno:

  1. 1Password desktop → Settings → Developer → «Use the SSH agent» ✅
  2. Almacena las claves SSH en el vault de 1Password y regístralas en GitHub
  3. $PROFILE de PowerShell: 
    $env:SSH_AUTH_SOCK = '\\.\pipe\openssh-ssh-agent'
  4. Nueva terminal → ssh -T git@github.com → Windows Hello una vez

Ahora SSH y la firma de commits funcionan sin archivos ~/.ssh/id_* en texto plano en el disco.

6. Verificación

  1. ssh -T git@github.com — autenticación correcta
  2. git clone git@github.com:tu/repo.git — sin solicitud de frase de contraseña (o un toque biométrico)
  3. git commit --allow-empty -m test && git log --show-signature -1 — «Good signature»
  4. El PR en GitHub muestra la insignia «Verified»
  5. git config user.email diferente en carpetas de trabajo y personales

Resolución de problemas

ssh: connect to host github.com port 22: Connection timed out

El cortafuegos corporativo bloquea el puerto 22. Usa SSH sobre el 443:

# ~/.ssh/config
Host github.com
  HostName ssh.github.com
  Port 443

Permission denied (publickey)

  • Permisos del archivo de clave — icacls ~/.ssh/id_ed25519 /inheritance:r /grant:r "$($env:USERNAME):(R)"
  • Clave pública no registrada en GitHub

GCM deshabilitado

git config --global credential.helper manager
git config --global credential.helperSelector prompt

Agente SSH de 1Password no detectado

  • Aplicación de escritorio en ejecución + sesión iniciada + opción Developer activada
  • Valor exacto de SSH_AUTH_SOCK (\\.\pipe\openssh-ssh-agent)
  • Conflicto: si el servicio del agente OpenSSH está en ejecución, su socket puede tener prioridad. Stop-Service ssh-agent o desactívalo

La firma de commit aparece como «Unverified»

  • Registra la clave SSH en GitHub como signing key (independiente de la de autenticación)
  • Falta git config --global gpg.format ssh
  • Clave corrupta — regenera y vuelve a registrar

includeIf no se activa

  • Se requiere Git 2.36+ (versiones antiguas de Git for Windows sin soporte)
  • La ruta de gitdir necesita barra final (C:/Users/me/work/)
  • Usa / en lugar de \ en Windows

Referencias

Registro de cambios

  • 2026-05-12: Primer borrador. GCM + claves SSH + firma SSH + múltiples cuentas + agente 1Password + seis casos de resolución de problemas.