Clave SSH para GitHub: configúrala una vez y olvídate del token

Si haces push por HTTPS, ya conoces el ritual: pegas tu token personal, funciona unas semanas, caduca, y vuelves a generar otro mientras Git te recuerda que “Support for password authentication was removed”. Configurar una clave SSH para GitHub arregla eso de una vez. Generas un par de claves en tu máquina, subes la mitad pública a tu cuenta, y a partir de ahí Git se autentica solo. Aquí tienes los comandos exactos, en orden, y lo que verás en pantalla para saber que cada paso ha ido bien.

¿SSH o HTTPS con token? ¿Cuál elijo?

Para tu máquina de trabajo habitual, SSH. Lo configuras una vez y te olvidas de credenciales. HTTPS con token personal (PAT) sigue teniendo su sitio, pero pensado para otros escenarios: un servidor de CI, un script que corre una vez, o una red que bloquea el puerto que usa SSH.

La diferencia práctica está en la comodidad y en dónde acaba viviendo la credencial, no en el nivel de seguridad.

	SSH	HTTPS + token (PAT)
Configuración inicial	Generar el par de claves y subir la pública. Cinco minutos.	Generar un token en la web y guardarlo.
Uso diario	Push y pull sin escribir nada	Pegas el token o dependes de un credential helper
Dónde vive la credencial	La privada, cifrada, en tu disco; nunca sale de tu máquina	El token, con permisos amplios, en tu gestor de credenciales
Buena opción para	Tu portátil o tu equipo de sobremesa de siempre	CI, servidores efímeros, redes con el puerto 22 cerrado
Caducidad	La clave no caduca; la revocas cuando quieras	El token caduca y toca renovarlo

Si vas a trabajar en equipo con Git y GitHub, SSH es además el flujo que casi todo el mundo espera: cuando alguien te dice “sube tu clave pública”, habla de esto.

¿Qué es una clave SSH y por qué son dos archivos?

Una clave SSH es un par de archivos matemáticamente ligados: uno privado y uno público. Piensa en un candado y su llave. El candado (la clave pública) lo puedes repartir a quien quieras; lo dejas colgado en GitHub. La llave (la clave privada) se queda solo contigo y no la enseñas a nadie.

Cuando Git se conecta, GitHub comprueba que tu llave privada encaja con el candado público que subiste, sin que la privada llegue a viajar por la red. Por eso subir a GitHub el archivo equivocado es el error clásico, y por eso insisto tanto en él más abajo. La regla se resume en una frase: la privada no sale de tu máquina jamás.

¿Cómo genero la clave con ssh-keygen?

El comando recomendado hoy usa el algoritmo Ed25519, más moderno y con claves más cortas que el viejo RSA ^[1]:

# -t ed25519 elige el tipo de clave; -C añade una etiqueta (tu email) para reconocerla luego
ssh-keygen -t ed25519 -C "tu_email@ejemplo.com"

El -C no es criptografía, es solo un comentario que se guarda al final de la clave pública. Te sirve para distinguir “portátil-trabajo” de “sobremesa-casa” cuando tengas varias en GitHub.

Acto seguido ssh-keygen te pregunta dónde guardar el archivo (acepta el sitio por defecto pulsando Enter) y te pide una passphrase:

> Enter passphrase (empty for no passphrase): [escribe una passphrase]
> Enter same passphrase again: [repítela]

La passphrase cifra tu clave privada en el disco. Es opcional, pero ponla: si alguien te copia el archivo id_ed25519, sin la passphrase no le sirve de nada. Al terminar, tienes dos archivos en tu carpeta ~/.ssh/:

• id_ed25519: la clave privada. No la abras, no la copies a ningún sitio, no la subas a ningún lado.
• id_ed25519.pub: la clave pública. Esta es la que subirás a GitHub dentro de un momento.

En macOS la ruta es /Users/TU_USUARIO/.ssh/, en Linux /home/TU_USUARIO/.ssh/ y en Windows C:\Users\TU_USUARIO\.ssh\. El nombre del archivo es el mismo en los tres.

¿Cómo cargo la clave en el ssh-agent?

El ssh-agent es un programa que guarda tu clave privada descifrada en memoria durante la sesión. Sin él, tendrías que teclear la passphrase en cada push y cada pull. Con él, la escribes una vez al añadir la clave y el agente responde por ti el resto del día.

Primero arráncalo, luego añade la clave:

# Arranca el agente en segundo plano y exporta sus variables de entorno a tu shell
eval "$(ssh-agent -s)"
# > Agent pid 59566

# Añade la clave privada al agente (te pedirá la passphrase una vez)
ssh-add ~/.ssh/id_ed25519

En macOS, para que la passphrase se guarde también en el Llavero y sobreviva a los reinicios, usa ssh-add --apple-use-keychain ~/.ssh/id_ed25519 ^[1]. Fíjate en un detalle: le pasas al agente la clave privada (id_ed25519), no la pública. El agente necesita la mitad secreta para firmar; la pública ya vive en GitHub.

¿Cómo añado la clave pública a GitHub?

Copia el contenido de tu archivo .pub y pégalo en la configuración de tu cuenta. En macOS lo mandas directo al portapapeles:

# macOS: copia la clave PÚBLICA al portapapeles
pbcopy < ~/.ssh/id_ed25519.pub

# Linux o cualquier sistema: imprímela y cópiala a mano desde la terminal
cat ~/.ssh/id_ed25519.pub

Lo que ves empieza por ssh-ed25519 AAAA... y acaba con el email que pusiste en -C. Esa línea entera es lo que va a GitHub. Luego, en la web ^[2]:

1. Foto de perfil (arriba a la derecha) > Settings.
2. En la barra lateral, sección “Access”, entra en SSH and GPG keys.
3. Pulsa New SSH key.
4. En Title, una etiqueta que reconozcas (“Portátil trabajo”). En Key type, deja Authentication Key. En Key, pega la línea que copiaste.
5. Add SSH key.

El Title es solo para tus ojos: te permite revocar la clave del portátil que perdiste sin tocar las demás. El tipo por defecto, Authentication Key, es el que sirve para autenticarte en Git; el otro, de firma, es para firmar commits y no lo necesitas aquí.

¿Cómo compruebo que funciona?

Lanza una conexión de prueba contra GitHub:

ssh -T git@github.com

La primera vez, SSH no reconoce el servidor y te avisa con la huella de su clave de host ^[3]:

The authenticity of host 'github.com (IP ADDRESS)' can't be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
Are you sure you want to continue connecting (yes/no)?

Esa huella es la de GitHub. Si coincide con la de su documentación, escribe yes. No vuelve a preguntar. Si todo está bien, GitHub responde:

Hi USERNAME! You've successfully authenticated, but GitHub does not provide shell access.

Ese mensaje confunde a mucha gente la primera vez. GitHub te saluda por tu nombre de usuario (la autenticación ha funcionado) y a la vez te dice que no vas a tener una shell en sus servidores. Es lo esperado: SSH aquí solo autentica operaciones de Git, no te da un terminal remoto. Si lees tu nombre, ya está.

Antes de tocar tu propia terminal, recorre el flujo completo en este ejercicio interactivo y fija cada paso:

Cargando ejercicio...

Cambiar un repositorio de HTTPS a SSH y clonar

Si ya tienes un repositorio clonado por HTTPS, no hace falta volver a bajarlo. Cambia la URL del remoto. Mira primero cómo lo tienes:

git remote -v
# origin  https://github.com/usuario/repo.git (fetch)
# origin  https://github.com/usuario/repo.git (push)

Si ves una URL que empieza por https://, cámbiala a la forma SSH con git remote set-url:

# Reemplaza la URL del remoto 'origin' por su equivalente SSH
git remote set-url origin git@github.com:usuario/repo.git

La sintaxis SSH git@github.com:usuario/repo.git es distinta a la HTTPS: usuario git, dos puntos, y la ruta del repo. A partir de ese cambio, tus push y pull salen por SSH sin pedir nada. Si quieres profundizar en cómo se gestionan estos remotos, tienes la guía de conectar un remoto de Git con GitHub.

Para repositorios nuevos, clona directamente con la URL SSH, que copias desde el botón “Code” > pestaña “SSH” en la página del repo:

git clone git@github.com:usuario/repo.git

Si es la primera vez que bajas un proyecto, la guía de cómo clonar un repositorio de Git cubre el resto de opciones de clonado.

Cuando quieras ir más allá de la autenticación y dominar ramas, merges y flujos de equipo, el curso Git de cero a profesional practica todo esto con ejercicios guiados como el de arriba.

Errores comunes

Subir la clave privada en lugar de la pública. Es el fallo más peligroso. Si en el campo Key de GitHub pegas el contenido de id_ed25519 (sin .pub), estás exponiendo tu secreto. La pública siempre empieza por ssh-ed25519; la privada empieza por -----BEGIN OPENSSH PRIVATE KEY-----. Si ves esa segunda línea al copiar, para: has abierto el archivo equivocado. Si llegaste a subirla o compartirla, bórrala de GitHub y genera un par nuevo.

Permission denied (publickey). GitHub rechaza la conexión porque no encuentra una clave válida. Casi siempre es una de dos: el agente no está arrancado (repite eval "$(ssh-agent -s)" y ssh-add), o la clave que tienes cargada no es la que subiste a GitHub. Comprueba qué claves conoce el agente con ssh-add -l.

Confundir la clave SSH con un Personal Access Token. Son mecanismos distintos y no intercambiables. El PAT es una contraseña larga que viaja por HTTPS; la clave SSH es un par candado/llave. Pegar un token en el campo de clave SSH de GitHub no funciona, y al revés tampoco.

Nombre de archivo personalizado sin configurar. Si generaste la clave con un nombre distinto al de por defecto (por ejemplo id_trabajo), SSH no la buscará sola. Díselo en ~/.ssh/config con una entrada IdentityFile ~/.ssh/id_trabajo, o cárgala siempre a mano con ssh-add.

Checklist

• La clave está generada con ssh-keygen -t ed25519 -C "tu_email"
• Tienes dos archivos en ~/.ssh/: id_ed25519 y id_ed25519.pub
• El ssh-agent está arrancado y la clave privada cargada con ssh-add
• En GitHub solo has pegado el contenido de id_ed25519.pub, como Authentication Key
• ssh -T git@github.com te saluda por tu nombre de usuario
• Tus repositorios usan una URL git@github.com:... en git remote -v

¿Te ha resultado útil? Recibe la siguiente guía de Git en equipo directamente en tu correo:

Un concepto nuevo cada semana

Suscribirme

Fuentes

1. Generating a new SSH key and adding it to the ssh-agent (GitHub Docs): comando ssh-keygen -t ed25519, rutas por defecto, arranque del agente y ssh-add (incluida la variante --apple-use-keychain en macOS).
2. Adding a new SSH key to your GitHub account (GitHub Docs): navegación Settings > SSH and GPG keys > New SSH key, campos Title y Key type, y comandos para copiar la clave pública.
3. Testing your SSH connection (GitHub Docs): comando ssh -T git@github.com, aviso de host key y mensaje de éxito exacto.
4. Using SSH over the HTTPS port (GitHub Docs): conexión por el puerto 443 a través de ssh.github.com cuando el puerto 22 está bloqueado.

Preguntas Frecuentes

¿Tengo que poner passphrase en mi clave SSH? ¿Qué pasa si la olvido?

Conviene, aunque no es obligatoria. La passphrase cifra tu clave privada en el disco, así que si alguien te copia el archivo, no puede usarlo sin ella. Si la olvidas, no hay forma de recuperarla: generas un par nuevo con ssh-keygen, subes la nueva pública a GitHub y borras la anterior. Con el ssh-agent solo la escribes una vez por sesión.

¿Puedo usar la misma clave SSH en varios ordenadores?

Técnicamente sí, pero es mejor una clave por máquina. Copiar la clave privada entre equipos multiplica los sitios desde donde puede filtrarse. Genera un par en cada ordenador y sube cada pública a GitHub con un Title distinto. Así, si pierdes el portátil, revocas solo esa clave y el resto sigue funcionando.

¿SSH funciona detrás de un firewall corporativo que bloquea el puerto 22?

A veces no por el puerto estándar, pero hay salida. GitHub ofrece SSH por el puerto 443, el mismo que usa el tráfico HTTPS, que casi ningún firewall bloquea. Lo pruebas con ssh -T -p 443 git@ssh.github.com y, si responde con el saludo habitual, añades una entrada en ~/.ssh/config para enrutar github.com por ese puerto ^[4].

¿La clave SSH para GitHub sustituye al login del navegador?

No. La clave SSH autentica las operaciones de Git desde tu terminal (clonar, push, pull). Para entrar en la web de github.com sigues usando tu usuario, tu contraseña y tu segundo factor. Son dos caminos de acceso independientes a la misma cuenta.