El uso de una SSH key con GitHub permite el acceso sin co­n­tra­se­ña a los re­po­si­to­rios Git por SSH. En lugar de ide­n­ti­fi­car a un usuario por su nombre de usuario y co­n­tra­se­ña, la máquina del de­sa­rro­lla­dor se au­te­n­ti­fi­ca a través de la clave SSH.

VPS gratis
Prueba un servidor virtual de forma gratuita durante 30 días

¡Prueba tu servidor virtual durante 30 días! Si lo solicitas, te re­em­bo­l­sa­re­mos todos los gastos in­cu­rri­dos.

¿Qué es una clave SSH?

SSH es la he­rra­mie­n­ta estándar para el acceso cifrado a sistemas remotos. SSH te permite iniciar sesión en un servidor desde otro equipo. Git utiliza SSH como protocolo de tra­n­s­fe­re­n­cia y permite el acceso de lectura y escritura a los re­po­si­to­rios remotos.

Se utiliza una conexión en­cri­p­ta­da para permitir la au­te­n­ti­ca­ción de la máquina y ga­ra­n­ti­zar que los datos tra­n­s­mi­ti­dos no puedan ser fa­l­si­fi­ca­dos. Sin esto, sería posible que personas no au­to­ri­za­das hicieran cambios ar­bi­tra­rios en los re­po­si­to­rios.

Git vía SSH utiliza cifrado asi­mé­tri­co como método de en­cri­p­ta­ción. En primer lugar, se crean un par de claves privadas y públicas. También se denomina “Public-Private Keypair”. La clave privada permanece en el propio ordenador del usuario. La clave pública se comparte con terceros, por ejemplo, GitHub.

Si utilizas una clave SSH para acceder a los re­po­si­to­rios de GitHub, no necesitas in­tro­du­cir una co­n­tra­se­ña. En general, el inicio de sesión sin co­n­tra­se­ña se considera más seguro, ya que los ke­y­lo­g­ge­rs o troyanos no pueden capturar ninguna co­n­tra­se­ña. En lugar de que una persona conozca la co­n­tra­se­ña, se au­te­n­ti­fi­ca una máquina en la que se almacena la clave privada.

El uso de Git a través de SSH es ex­tre­ma­da­me­n­te práctico. Una vez co­n­fi­gu­ra­da, la clave SSH permite el acceso pe­r­ma­ne­n­te a GitHub sin más in­te­r­ve­n­ción. Otros pro­to­co­los y servicios también se be­ne­fi­cian de las claves SSH para una conexión de red en­cri­p­ta­da. Además de Git vía SSH, se puede utilizar el protocolo seguro SFTP para in­te­r­ca­m­biar archivos con los se­r­vi­do­res sin necesidad de ninguna otra co­n­fi­gu­ra­ción.

La conexión a los re­po­si­to­rios Git se realiza no­r­ma­l­me­n­te desde la línea de comandos. Si has co­n­fi­gu­ra­do una clave SSH, puedes realizar un push al propio re­po­si­to­rio sin problemas:

cd ./carpeta_con_repositorio_git/
git push

Además de la apli­ca­ción de línea de comandos, las apli­ca­cio­nes de interfaz gráfica de usuario también se be­ne­fi­cian de tener una clave SSH co­n­fi­gu­ra­da. Los programas FTP modernos soportan el protocolo de tra­n­s­fe­re­n­cia de archivos vía SSH (SFTP por sus siglas en inglés), que se basa en SSH y utiliza las claves SSH exi­s­te­n­tes.

Cómo utilizar las claves SSH con GitHub

Para acceder con una clave SSH o SSH key a GitHub, debes depositar la clave pública en GitHub. La clave privada permanece en tu propio ordenador. La máquina en la que trabajas se au­te­n­ti­fi­ca en GitHub co­m­pa­ra­n­do los datos de la clave. Esto te permite tener acceso de escritura a tus propios re­po­si­to­rios. Este método también funciona con al­te­r­na­ti­vas a GitHub como Gitlab o Bitbucket.

Por muy prácticas que sean las claves SSH, hay que tener cuidado al ma­ne­jar­las. No compartas tu clave privada en ninguna ci­r­cu­n­s­ta­n­cia. La clave privada puede permitir que otra persona se haga pasar por ti y podría entrar en un servidor o cambiar el código en los re­po­si­to­rios en tu nombre.

Re­qui­si­tos para utilizar GitHub con la clave SSH

Este artículo está orientado a quienes trabajan en un entorno tipo Linux. Esto incluye Linux/Unix, macOS, así como Windows con WSL2 instalado. Además, deben cumplirse las si­guie­n­tes co­n­di­cio­nes:

  • Git instalado
  • SSH instalado
  • Cuenta de GitHub creada

Primero, hay que ase­gu­rar­se de que se cumplen los re­qui­si­tos locales. Con el siguiente comando comprueba si Git y SSH están in­s­ta­la­dos. A menos que recibas un mensaje de error “git not found” o “git not found”, ambos están presentes:

which git ssh
Imagen: Probando la instalación de Git y SSH
Git y SSH están in­s­ta­la­dos en nuestro sistema. Estamos buscando, por ejemplo, un comando in­e­xi­s­te­n­te “unknown”.

Además, crea el di­re­c­to­rio .ssh en la carpeta del usuario si no existe ya:

mkdir -vp ~/.ssh/

A co­n­ti­nua­ción, descubre cómo generar una clave SSH y re­gi­s­trar­la, con el comando de ssh-keygen en GitHub. Una vez co­m­ple­ta­do este paso, podrás ver cómo depositar la clave SSH pública en GitHub y cómo acceder a los re­po­si­to­rios Git a través de SSH:

  1. Crear un par de claves SSH en tu propio sistema
  2. Depositar la clave SSH pública en GitHub
  3. Acceder al re­po­si­to­rio de GitHub con la clave SSH

Crear y registrar la clave SSH en tu propio sistema

Como primer paso, crea un par de claves SSH públicas y privadas en nuestro sistema local. Copia los comandos uti­li­za­dos en el mismo orden y eje­cú­ta­los en tu línea de comandos. Para ello, sigue la do­cu­me­n­ta­ción oficial de GitHub. El pro­ce­di­mie­n­to cambia de vez en cuando. Así que para so­lu­cio­nar errores de SSH no está de más revisar la página cada cierto tiempo.

En primer lugar, iniciamos el generador de claves SSH para crear un par de claves públicas/privadas para GitHub. Utiliza el comando ssh-keygen, que está di­s­po­ni­ble en el sistema por defecto como parte de la in­s­ta­la­ción de OpenSSH.

Teclea ssh-keygen en la línea de comandos e inseta tres opciones:

  • Opción -f seguida de la ruta y el nombre de la nueva clave
  • Opción -t seguida del nombre del algoritmo, en este caso ed25519
  • Opción -C seguida de una dirección de correo ele­c­tró­ni­co como co­me­n­ta­rio
ssh-keygen -f "$HOME/.ssh/github_id_ed25519" -t ed25519 -C "correo_de_ejemplo@ejemplo.es"
bash
Nota

Puedes utilizar cualquier dirección de correo ele­c­tró­ni­co para generar el par de claves. Esto sirve solo como etiqueta; no tiene que ser la misma dirección que usas para iniciar sesión en GitHub.

El comando ssh-keygen pide que es­pe­ci­fi­ques una “frase de co­n­tra­se­ña” para la clave privada. A di­fe­re­n­cia de una co­n­tra­se­ña normal, una frase de co­n­tra­se­ña puede contener espacios. La frase de co­n­tra­se­ña debe tener varias palabras, para que sea fácil de recordar y difícil de adivinar. Para mayor seguridad, incluye algunos números o ca­ra­c­te­res es­pe­cia­les. Escribe la frase de co­n­tra­se­ña y pulsa "Intro". Repite el proceso para completar la creación del par de claves SSH.

Imagen: Creación de un par de claves SSH para GitHub
Hemos generado la clave SSH para usarla con GitHub.
Consejo

USA el algoritmo Ed25519 para el par de claves. De hecho, hay toda una gama de al­go­ri­t­mos di­s­po­ni­bles. Descubre los métodos de en­cri­p­ta­do de un vistazo en un artículo aparte.

Antes de poder utilizar la clave SSH recién creada con GitHub, realiza otro paso. Esto es opcional, pero muy re­co­me­n­da­ble. Añade la clave privada al llamado “SSH-Agent” o agente SSH. Se trata de un programa en segundo plano que se ejecuta en el sistema local. Teclea el siguiente comando en la línea de comandos y escribe la frase de co­n­tra­se­ña cuando se te pida:

  • Windows / Linux
ssh-add ~/.ssh/github_id_ed25519
  • macOS hasta 11 Big Sur
ssh-add -K ~/.ssh/github_id_ed25519
  • macOS desde 12 Monterey
ssh-add --apple-use-keychain ~/.ssh/github_id_ed25519

El agente SSH tiene acceso a las claves privadas añadidas y permite uti­li­zar­las para las co­ne­xio­nes sin tener que in­tro­du­cir la frase de co­n­tra­se­ña cada vez. Pero el agente SSH puede hacer aún más:

Cita

“ssh-agent is a program that can hold a user's private key, so that the private key pa­s­s­ph­ra­se only needs to be supplied once. A co­n­ne­c­tion to the agent can also be forwarded when logging into a server, allowing SSH commands on the server to use the agent running on the user's desktop”. Fuente: https://www.ssh.com/academy/ssh/keygen#adding-the-key-to-ssh-agent

Tra­du­c­ción: “ssh-agent es un programa que puede mantener la clave privada de un usuario, de modo que la frase de co­n­tra­se­ña de la clave privada solo tiene que su­mi­ni­s­trar­se una vez. También se puede reenviar una conexión al agente cuando se inicia la sesión en un servidor, lo que permite que los comandos SSH en el servidor utilicen el agente que se ejecuta en el es­cri­to­rio del usuario.” (traducido por IONOS)

Depositar la clave SSH en GitHub

Has creado un par de de claves SSH en nuestro sistema local. Con esto, la mitad de la co­mu­ni­ca­ción permanece en­cri­p­ta­da cuando se utiliza Git por SSH. A co­n­ti­nua­ción, hay que depositar la clave SSH pública en GitHub.

Imagen: Página de configuración de la cuenta de GitHub
Accede a tu cuenta de GitHub y navega hasta la página de co­n­fi­gu­ra­ción de claves.
Imagen: Configuración de GitHub para añadir una clave SSH
Haz clic en el botón “New SSH key” en “SSH keys” para abrir la página para añadir una nueva clave.

Ahora necesitas el contenido de la clave pública. Pasa a tu línea de comandos local y teclea el siguiente comando:

cat ~/.ssh/github_id_ed25519.pub
Nota

Atención: el nombre de archivo de una clave pública termina en .pub para “clave pública”. Sin embargo, la clave privada no termina en .priv. En cambio, la clave privada no tiene extensión. Comparte úni­ca­me­n­te la clave pública con GitHub y otras personas.

Imagen: Contenido de la clave pública en la línea de comandos
Copia la clave pública emitida y vuelve a la página de GitHub.
Imagen: Clave SSH pública copiada en la página de configuración de GitHub
Pega la clave pública copiada y, op­cio­na­l­me­n­te, asigna un título. Guarda los cambios haciendo clic en el botón “Add SSH key”.
Imagen: Visión general de las claves SSH añadidas en GitHub
La clave SSH recién añadida para GitHub se muestra en el resumen de claves.

Acceder al re­po­si­to­rio de GitHub con la clave SSH

Tras haber generado las claves SSH de forma local y de­po­si­ta­do la clave pública en GitHub, hay que probar si la conexión funciona. Para ello recurre al siguiente comando:

ssh -T git@github.com
Imagen: Prueba de conexión positiva con GitHub a través de SSH
La conexión en­cri­p­ta­da con GitHub está fu­n­cio­na­n­do.

Si es la primera vez que te conectas a GitHub desde esa máquina, también tendrás que añadir el servidor a los “known hosts” o hosts conocidos:

Imagen: Añadir el servidor GitHub a los hosts SSH conocidos
Confirma la adición del servidor es­cri­bie­n­do “yes” y pulsando la tecla “Intro”.

Al acceder a los re­po­si­to­rios de GitHub, se distingue entre acceso de lectura y de escritura. Cua­l­quie­ra puede leer los re­po­si­to­rios públicos; no se requiere au­te­n­ti­ca­ción, es decir, no se necesita una clave SSH.

Para descargar un re­po­si­to­rio como copia local, usa el comando git clone. A co­n­ti­nua­ción, se presenta un ejemplo con el re­po­si­to­rio de la popular he­rra­mie­n­ta de red cURL. Accede a la página de GitHub del re­po­si­to­rio público re­po­si­to­rio cURL y copia la URL del clon:

Imagen: Página de resumen del repositorio cURL
Resumen del código del re­po­si­to­rio cURL. / Fuente: https://github.com/curl/curl
Imagen: Clonar url del repositorio cURL copiado
Copiamos la "URL del clon" del re­po­si­to­rio cURL. / Fuente: https://github.com/curl/curl

Equipados con la URL del clon, se vuelve a la línea de comandos local. Crea un re­po­si­to­rio de carpetas de ejemplo en el es­cri­to­rio y pasa a trabajar en él. A co­n­ti­nua­ción, hay que clonar el re­po­si­to­rio cURL usando git clone con la URL de clonación:

cd ~/Desktop/
mkdir -p repo && cd repo
git clone https://github.com/curl/curl.git
Imagen: Clonación del repositorio cURL en la línea de comandos local
El re­po­si­to­rio cURL clonado está ahora en la carpeta curl.

Pasa a la carpeta del re­po­si­to­rio cURL y usa el comando git status para mostrar el estado del re­po­si­to­rio:

cd ~/Desktop/repo/curl/
git status
Imagen: Estado del repositorio local cURL
El resultado de git status muestra que el estado es normal.

El comando git pull, que actualiza un re­po­si­to­rio, también requiere un acceso de solo lectura. Para ello, ejecuta git pull en la carpeta del re­po­si­to­rio; en principio esto funciona, aunque pro­ba­ble­me­n­te no haya aún cambios:

git pull

Intenta escribir en el re­po­si­to­rio de GitHub uti­li­za­n­do el comando git push:

Imagen: Resultado de git pull y git push del repositorio local cURL
Git pull funciona; git push falla porque la máquina no está au­te­n­ti­ca­da. 
git push

¿Por qué sucede esto? La URL de clonación utilizada para clonar el re­po­si­to­rio público cURL comienza con HTTPS. En co­n­se­cue­n­cia, para el clon local, una URL HTTPS se almacena como “Origin” u origen. Pasa a comprobar el origen con el comando git show::

git remote -v show
Imagen: Visión remota del repositorio local cURL en la línea de comandos
Se muestran las URL de las ope­ra­cio­nes git fetch y push.

Para el acceso de lectura, una URL HTTPS es su­fi­cie­n­te, pero se necesita una clave SSH para escribir en los re­po­si­to­rios de GitHub. Esto se debe a que la au­te­n­ti­ca­ción de usuarios por nombre de usuario/co­n­tra­se­ña no se admite en GitHub desde agosto de 2021.

Para probar git push de todas formas, hay un truco. Primero, crea en GitHub un re­po­si­to­rio vacío:

Imagen: Crear nuevo repositorio en GitHub
Creación de un nuevo re­po­si­to­rio llamado “test”.
Imagen: Vista general de un repositorio GitHub vacío
Nuestro re­po­si­to­rio de GitHub vacío contiene in­s­tru­c­cio­nes para llenarlo de código.

Siguiendo las in­s­tru­c­cio­nes de GitHub, hay que cambiar la URL push del clon local de cURL en nuestro sistema para utilizar nuestro re­po­si­to­rio vacío de GitHub como origen. También establece la rama como “main” o principal. A co­n­ti­nua­ción, ejecuta git push; la operación se completa con éxito y utiliza la clave SSH pre­via­me­n­te creada para la au­te­n­ti­ca­ción en GitHub.

git remote set-url origin git@github.com:<user>/test.git</user>
git branch -M main
git push -u origin main
Imagen: Cambiar la URL del push y el Git push del repositorio local
Git push funciona después de cambiar la URL del push.

Utilizar varias claves SSH para di­fe­re­n­tes cuentas de GitHub

Es posible utilizar una sola clave SSH para di­fe­re­n­tes cuentas de GitHub u otras cuentas sin ningún problema. Recuerda: puedes compartir la clave pública.

Té­c­ni­ca­me­n­te, puedes utilizar tus propias claves SSH para di­fe­re­n­tes servicios. Hay dos métodos posibles:

  1. Usar el comando SSH con pa­rá­me­tros
  2. Crear archivo de co­n­fi­gu­ra­ción SSH

Los comandos SSH con pa­rá­me­tros pueden resultar muy largos, por lo que no mostramos este enfoque aquí. En general, es más co­n­ve­nie­n­te trabajar con un archivo de co­n­fi­gu­ra­ción SSH. Esto requiere un poco más de esfuerzo en la co­n­fi­gu­ra­ción de tu propio sistema, pero solo tienes que hacerlo una vez. A co­n­ti­nua­ción, se muestra un resumen de las carpetas y archivos que in­te­r­vie­nen en la co­n­fi­gu­ra­ción de SSH:

Co­n­fi­gu­ra­ción SSH Ruta Acla­ra­ción
Carpeta de co­n­fi­gu­ra­ción ~/.ssh/ Contiene la co­n­fi­gu­ra­ción de SSH y los pares de claves
Clave privada ~/.ssh/key-name Clave privada de un par de claves
Clave pública ~/.ssh/key-name.pub Clave pública de un par de claves
Archivo de co­n­fi­gu­ra­ción ~/.ssh/config Archivo de co­n­fi­gu­ra­ción SSH
Hosts conocidos ~/.ssh/known_hosts Lista de hosts co­ne­c­ta­dos en el pasado

Primero crea el archivo de co­n­fi­gu­ra­ción SSH. Establece los derechos de usuario y abre el archivo en el editor de línea de comandos:

touch ~/.ssh/config
chmod 600 ~/.ssh/config
nano ~/.ssh/config

A co­n­ti­nua­ción, copia el siguiente bloque en el editor y sigue las capturas de pantalla para guardar el archivo:

# Github
Host github github.com
    HostName github.com
    User git
    IdentityFile "~/.ssh/github_id_ed25519"
    IdentitiesOnly yes
Imagen: Insertar la configuración de GitHub en el archivo de configuración de SSH
Pega el bloque de co­n­fi­gu­ra­ción y pulsar Ctrl + X para escribir los cambios y cierra el editor.
Imagen: Escribir el archivo de configuración SSH modificado
Confirma el nombre del archivo pulsando “Intro”.
Imagen: Confirmar los cambios en el archivo SSH Config
Confirma la escritura de los cambios pulsando “Intro”.

Después de insertar el bloque de co­n­fi­gu­ra­ción de GitHub, puedes es­ta­ble­cer una conexión SSH es­pe­ci­fi­ca­n­do la abre­via­tu­ra de host definida “github”:

ssh -T github

Sigue el esquema mostrado y añade bloques de co­n­fi­gu­ra­ción para servicios o cuentas adi­cio­na­les al archivo de co­n­fi­gu­ra­ción SSH. A co­n­ti­nua­ción, tienes un resumen de los pa­rá­me­tros uti­li­za­dos:

Co­n­fi­gu­ra­ción Ex­pli­ca­ción Ejemplo
Host Puede contener cualquier número de nombres github.com github
HostName Nombre de host del sistema remoto en el que se está eje­cu­ta­n­do SSH; también se puede utilizar una dirección IP github.com
User Usuario Git en el sistema remoto; debe ser copiado exac­ta­me­n­te git
Ide­n­ti­t­y­Fi­le Ruta completa a la clave privada. Ajústala si utiliza varias teclas ~/.ssh/github_id_ed25519
Ide­n­ti­tie­sO­n­ly Es­pe­ci­fi­ca que el acceso para este host solo se permite por clave yes

Un último consejo. Si creas co­n­fi­gu­ra­cio­nes SSH para varios hosts con tus propias claves, debes añadir un bloque con co­n­fi­gu­ra­cio­nes para hosts no listados al final del archivo:

# For all hosts
Host *
IdentitiesOnly no
IgnoreUnknown UseKeychain, AddKeysToAgent
UseKeychain yes
AddKeysToAgent yes

Esto permite el acceso sin una clave SSH a hosts no es­pe­ci­fi­ca­dos. Así, puedes co­ne­c­tar­te a un host a través del comando SSH con tu nombre de usuario e in­tro­du­cir la co­n­tra­se­ña al co­ne­c­tar­se:

ssh user@host

Sin la línea “Ide­n­ti­tie­sO­n­ly no” en la co­n­fi­gu­ra­ción final, SSH intenta todas las claves en ~./ssh/ una tras otra para co­ne­c­tar­se al servidor. Si no hay ninguna clave que coincida, se produce el error “Too many au­the­n­ti­ca­tion failures”, que refleja “De­ma­sia­dos fallos de au­te­n­ti­ca­ción”.

Ir al menú principal