Cómo solucionar 'Permission denied (publickey)' al hacer push a GitHub

¿Obtienes un error ‘Permission denied (publickey)’ al intentar hacer push a GitHub? Este error significa que GitHub no puede autenticarte debido a un problema con la clave SSH. Vamos a solucionarlo rápidamente.

Qué significa este error

El error ‘Permission denied (publickey)’ ocurre cuando Git intenta conectarse a GitHub usando SSH, pero la autenticación falla. Piensa en las claves SSH como una contraseña especial que permite a tu computadora comunicarse con GitHub de forma segura.

Esta guía cubre las tres causas principales y te muestra exactamente cómo solucionar cada una.

Las tres causas principales (y cómo solucionarlas)

1. No hay claves SSH creadas en tu computadora

Verificación rápida:

ls -la ~/.ssh

Si ves “No such file or directory” o la carpeta está vacía, necesitas crear claves SSH.

Solución: Genera un nuevo par de claves SSH:

ssh-keygen -t ed25519 -C "your-email@example.com"

Presiona Enter tres veces para aceptar los valores predeterminados. Esto crea dos archivos:

• ~/.ssh/id_ed25519 (clave privada - mantenla en secreto)
• ~/.ssh/id_ed25519.pub (clave pública - compártela con GitHub)

2. Clave pública no agregada a GitHub

Incluso con las claves SSH creadas, GitHub no te reconocerá hasta que agregues tu clave pública a tu cuenta.

Solución: Primero, copia tu clave pública:

cat ~/.ssh/id_ed25519.pub

Luego agrégala a GitHub:

1. Ve a configuración SSH de GitHub
2. Haz clic en “New SSH key”
3. Pega tu clave y guarda

3. Formato de URL remota incorrecto

Las URLs SSH de GitHub deben comenzar con git@github.com: - no con tu correo electrónico o nombre de usuario.

Verifica tu URL actual:

git remote -v

Formato correcto:

git@github.com:username/repository.git

Formatos incorrectos:

youremail@github.com:username/repository.git  ❌
https://github.com/username/repository.git    ❌ (esto es HTTPS, no SSH)

Solución: Actualiza a la URL SSH correcta:

git remote set-url origin git@github.com:username/repository.git

Verifica que todo funciona

Prueba tu conexión SSH a GitHub:

ssh -T git@github.com

Deberías ver:

Hi username! You've successfully authenticated...

Si esto funciona, ahora puedes hacer push a GitHub sin el error de permiso denegado.

Problemas comunes de solución de problemas

Agente SSH no está ejecutándose

Si tu clave existe pero aún no funciona, es posible que el agente SSH no esté ejecutándose.

Solución:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Múltiples cuentas de GitHub

Gestionar múltiples cuentas requiere un archivo de configuración SSH. Crea ~/.ssh/config:

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

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

Luego clona usando:

git clone git@github.com-work:company/repository.git

Notas específicas de plataforma

• Usuarios de Windows: Usa Git Bash en lugar de Command Prompt o PowerShell
• Usuarios de macOS/Linux: Usa Terminal

Ambas plataformas siguen los mismos comandos mostrados anteriormente.

Conclusión

El error ‘Permission denied (publickey)’ es frustrante pero fácil de solucionar. En la mayoría de los casos, solo necesitas crear claves SSH y agregar la clave pública a GitHub. Recuerda verificar tu conexión con ssh -T git@github.com antes de hacer push.

Una vez configurado correctamente, nunca volverás a ver este error para ese repositorio.

Preguntas frecuentes

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.