Manual de Configuración de SSH Keys con GitLab

Este manual te guiará en la configuración de llaves SSH para conectarte a GitLab desde macOS y Ubuntu.

Tabla de Contenidos

1. Configuración en macOS
2. Configuración en Ubuntu Server
3. Agregar SSH Key a GitLab
4. Verificar la Conexión
5. Solución de Problemas

---

Configuración en macOS

1. Generar la Llave SSH

Abre la Terminal y ejecuta el siguiente comando, reemplazando el correo con el tuyo:

ssh-keygen -t ed25519 -C "correo@dominio.com"

Durante el proceso:

• Te preguntará dónde guardar la llave (presiona Enter para usar la ubicación por defecto: ~/.ssh/id_ed25519)
• Te pedirá una contraseña (passphrase). Puedes dejarla vacía o agregar una para mayor seguridad
• Confirma la contraseña si decidiste usar una

2. Copiar la Llave Pública

Para copiar la llave pública al portapapeles, ejecuta:

tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy

Este comando elimina los saltos de línea y copia la llave directamente al portapapeles de macOS.

3. Configurar el Archivo SSH Config

Crea o edita el archivo de configuración SSH:

nano ~/.ssh/config

Agrega la siguiente configuración:

Host gitlab.sani.capital
    HostName gitlab.sani.capital
    Port 2222
    User git
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

Explicación de los parámetros:

• Host: Alias para conectarte fácilmente
• HostName: Dominio o IP del servidor GitLab
• Port: Puerto SSH personalizado (el estándar es 22)
• User: Usuario de Git
• IdentityFile: Ruta a tu llave privada
• IdentitiesOnly: Usa solo la llave especificada

Guarda el archivo (Ctrl+O, Enter, Ctrl+X en nano).

4. Establecer Permisos Correctos

chmod 600 ~/.ssh/config
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

---

Configuración en Ubuntu Server

1. Generar la Llave SSH

Conéctate al servidor Ubuntu vía SSH y ejecuta:

ssh-keygen -t ed25519 -C "correo@dominio.com"

Sigue el mismo proceso que en macOS para guardar la llave y establecer una contraseña.

2. Copiar la Llave Pública

En Ubuntu, puedes visualizar la llave pública con:

cat ~/.ssh/id_ed25519.pub

Copia manualmente todo el contenido que aparece en pantalla (comienza con ssh-ed25519 y termina con tu correo).

3. Configurar el Archivo SSH Config

nano ~/.ssh/config

Agrega la misma configuración que en macOS:

Host gitlab.sani.capital
    HostName gitlab.sani.capital
    Port 2222
    User git
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

4. Establecer Permisos Correctos

chmod 600 ~/.ssh/config
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

---

Agregar SSH Key a GitLab

Para el Servidor de OVH (gitlab.sani.capital)

1. Inicia sesión en tu instancia de GitLab: https://gitlab.sani.capital
2. Haz clic en tu avatar (esquina superior derecha) → Preferences
3. En el menú lateral, selecciona SSH Keys
4. Pega la llave pública que copiaste anteriormente en el campo “Key”
5. Dale un título descriptivo (ej: “MacBook Pro Personal” o “Servidor Ubuntu OVH”)
6. Opcionalmente, establece una fecha de expiración
7. Haz clic en Add key

Configurar Múltiples Cuentas del Team (Opcional)

Si necesitas configurar SSH keys para varios miembros del equipo:

En el archivo ~/.ssh/config, agrega entradas separadas:

# Usuario 1
Host gitlab-usuario1
    HostName gitlab.sani.capital
    Port 2222
    User git
    IdentityFile ~/.ssh/id_ed25519_usuario1
    IdentitiesOnly yes

# Usuario 2
Host gitlab-usuario2
    HostName gitlab.sani.capital
    Port 2222
    User git
    IdentityFile ~/.ssh/id_ed25519_usuario2
    IdentitiesOnly yes

Al clonar repositorios, usa el alias correspondiente:

git clone git@gitlab-usuario1:grupo/proyecto.git

---

Verificar la Conexión

Prueba Básica de Conexión

ssh -T git@gitlab.sani.capital

Si todo está configurado correctamente, deberías ver un mensaje como:

Welcome to GitLab, @tu-usuario!

Prueba con Verbose (para debugging)

Si tienes problemas, ejecuta con el flag -v:

ssh -vT git@gitlab.sani.capital

Probar Clonado de Repositorio

git clone git@gitlab.sani.capital:grupo/nombre-del-proyecto.git

---

Solución de Problemas

Error: “Permission denied (publickey)”

Causas comunes:

1. La llave pública no está agregada en GitLab
2. Los permisos de los archivos SSH son incorrectos
3. El archivo config tiene errores de sintaxis

Soluciones:

# Verificar que la llave está cargada
ssh-add -l

# Agregar la llave manualmente si es necesario
ssh-add ~/.ssh/id_ed25519

# Verificar permisos
ls -la ~/.ssh/

Error: “Connection refused” o “Connection timed out”

Causas comunes:

1. El puerto está bloqueado por firewall
2. El servidor GitLab está caído
3. Puerto incorrecto en la configuración

Soluciones:

# Verificar conectividad al puerto
nc -zv gitlab.sani.capital 2222

# Verificar configuración
cat ~/.ssh/config

La Llave No Se Carga Automáticamente

Agrega la llave al agente SSH:

macOS:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Ubuntu:

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

Múltiples Llaves SSH

Si tienes varias llaves y Git usa la incorrecta:

# Especifica la llave en el comando git
GIT_SSH_COMMAND="ssh -i ~/.ssh/id_ed25519" git clone git@gitlab.sani.capital:grupo/proyecto.git

O configura por repositorio:

cd tu-repositorio
git config core.sshCommand "ssh -i ~/.ssh/id_ed25519 -F /dev/null"

---

Configuración Git Global (Recomendado)

Después de configurar SSH, establece tu identidad Git:

git config --global user.name "Tu Nombre"
git config --global user.email "correo@dominio.com"

Para verificar la configuración:

git config --list

---

Notas de Seguridad

1. Nunca compartas tu llave privada (id_ed25519). Solo comparte la pública (.pub)
2. Usa passphrase para tus llaves en entornos de producción
3. Rota las llaves periódicamente (cada 6-12 meses)
4. Elimina llaves antiguas de GitLab cuando ya no las uses
5. Respalda tus llaves en un lugar seguro (como un gestor de contraseñas)

---

Comandos de Referencia Rápida

# Generar llave
ssh-keygen -t ed25519 -C "correo@dominio.com"

# Ver llave pública (macOS)
cat ~/.ssh/id_ed25519.pub | pbcopy

# Ver llave pública (Ubuntu)
cat ~/.ssh/id_ed25519.pub

# Probar conexión
ssh -T git@gitlab.sani.capital

# Ver llaves cargadas
ssh-add -l

# Agregar llave al agente
ssh-add ~/.ssh/id_ed25519

# Editar config
nano ~/.ssh/config

---

Recursos Adicionales

• Documentación oficial de GitLab sobre SSH
• Guía de SSH de GitHub (aplica para GitLab también)
• Soporte: Contacta al administrador del servidor GitLab para problemas específicos del servidor