Cómo Instalar GitLab en Ubuntu: Guía Completa Paso a Paso

GitLab es una de las plataformas DevOps de código abierto más potentes disponibles hoy en día, ofreciendo un conjunto completo de herramientas que incluyen control de versiones basado en Git, canalizaciones de integración continua/entrega continua (CI/CD), seguimiento de problemas y características de colaboración en equipo — todo bajo un mismo techo. Ya sea que estés gestionando un pequeño equipo de desarrollo o ejecutando proyectos de software a escala empresarial, alojar GitLab en Ubuntu te brinda control total sobre tus datos, flujos de trabajo e infraestructura.

Esta guía te acompaña en cada paso de la instalación y configuración de GitLab Community Edition (CE) en un servidor Ubuntu, desde la preparación inicial del sistema hasta la habilitación de HTTPS y la gestión de servicios.

Requisitos previos

Antes de comenzar, asegúrate de tener lo siguiente en su lugar:

• Un servidor ejecutando Ubuntu 20.04 o 22.04 LTS (se recomienda instalación nueva)
• Un mínimo de 4 GB RAM y 2 núcleos de CPU (GitLab recomienda al menos 4 núcleos para uso en producción)
• Acceso root o sudo al servidor
• Un nombre de dominio registrado apuntando a la dirección IP de tu servidor (opcional pero altamente recomendado para HTTPS)
• Puertos 80 y 443 abiertos en tu firewall

> Consejo: Para el mejor rendimiento de GitLab, considera implementar en un plan de VPS Hosting con suficientes recursos de RAM y CPU. Los planes VPS de AlexHost están optimizados para cargas de trabajo Linux y vienen con acceso root completo, lo que los hace un entorno ideal para plataformas DevOps autohospedadas como GitLab.

Paso 1: Actualizar paquetes del sistema

Antes de instalar cualquier software, es crítico asegurar que el índice de paquetes de tu sistema y los paquetes instalados estén completamente actualizados. Esto previene conflictos de dependencias y asegura que estés trabajando con los últimos parches de seguridad.

sudo apt update && sudo apt upgrade -y

Espera a que se complete el proceso de actualización antes de proceder al siguiente paso.

Paso 2: Instalar dependencias requeridas

GitLab requiere varios paquetes de apoyo para funcionar correctamente, incluyendo herramientas para comunicación segura, gestión de zonas horarias y scripting. Instálalos con el siguiente comando:

sudo apt install -y curl openssh-server ca-certificates tzdata perl

Aquí está lo que hace cada paquete:

Paso 3: Agregar el repositorio oficial de GitLab

GitLab mantiene un repositorio de paquetes oficial que hace que la instalación y futuras actualizaciones sean directas. Usa el siguiente comando para descargar y ejecutar el script de configuración del repositorio:

curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash

Este script automáticamente:

• Detecta tu versión de Ubuntu
• Agrega el repositorio de paquetes de GitLab a tus fuentes de APT
• Importa la clave de firma GPG del repositorio para verificación de paquetes

Una vez que el script se complete, tu sistema está listo para instalar GitLab directamente desde la fuente oficial.

Paso 4: Instalar GitLab Community Edition

Ahora instala GitLab CE usando el gestor de paquetes apt. Debes establecer la variable de entorno EXTERNAL_URL a la URL o dirección IP a través de la cual los usuarios accederán a tu instancia de GitLab.

Si tienes un nombre de dominio:

sudo EXTERNAL_URL="https://gitlab.yourdomain.com" apt install gitlab-ce

Si estás usando una dirección IP (por ejemplo, para un servidor local o privado):

sudo EXTERNAL_URL="http://YOUR_SERVER_IP" apt install gitlab-ce

Reemplaza gitlab.yourdomain.com o YOUR_SERVER_IP con tu dominio o dirección IP real.

> Nota: El proceso de instalación puede tomar varios minutos ya que descarga y configura todos los componentes de GitLab, incluyendo PostgreSQL, Redis, NGINX y Sidekiq.

Durante la instalación, GitLab:

• Instalará todos los servicios incluidos (base de datos, caché, servidor web, etc.)
• Se configurará a sí mismo basándose en el EXTERNAL_URL que proporcionaste
• Generará archivos de configuración iniciales en /etc/gitlab/

Paso 5: Ejecutar la reconfiguración de GitLab

Después de la instalación, ejecuta el comando de reconfiguración para finalizar la configuración, inicializar la base de datos e iniciar todos los servicios de GitLab:

sudo gitlab-ctl reconfigure

Este comando lee la configuración de /etc/gitlab/gitlab.rb y aplica todos los ajustes. También genera certificados SSL (si Let’s Encrypt está configurado), configura el esquema de la base de datos e inicia todos los servicios de fondo requeridos.

Deberías ver una salida larga terminando con un mensaje similar a:

gitlab Reconfigured!

Paso 6: Acceder a GitLab en tu navegador web

Una vez que la reconfiguración se complete, abre tu navegador web y navega a la URL que especificaste durante la instalación:

https://gitlab.yourdomain.com

o

http://YOUR_SERVER_IP

Primer inicio de sesión

En tu primera visita, GitLab te pedirá que establezca una contraseña de administrador. Después de establecerla, inicia sesión usando las siguientes credenciales:

• Nombre de usuario: root
• Contraseña: La contraseña que acabas de crear

> Consejo de seguridad: Cambia las credenciales de la cuenta root predeterminada inmediatamente después de tu primer inicio de sesión. Crea una cuenta de administrador personal y restringe la cuenta root solo para uso de emergencia.

Paso 7: Configurar notificaciones por correo electrónico de GitLab (Opcional)

Enviar notificaciones por correo electrónico es esencial para una instancia de GitLab en producción — habilita características como verificación de cuenta, actualizaciones de solicitudes de fusión, alertas de CI/CD y restablecimiento de contraseñas. Configura los ajustes SMTP en el archivo de configuración principal de GitLab:

sudo nano /etc/gitlab/gitlab.rb

Agrega o modifica el siguiente bloque de configuración SMTP:

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.yourmailprovider.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "your_email@yourdomain.com"
gitlab_rails['smtp_password'] = "your_email_password"
gitlab_rails['smtp_domain'] = "yourdomain.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true

Guarda el archivo y aplica los cambios:

sudo gitlab-ctl reconfigure

> ¿Buscas una infraestructura de correo electrónico confiable? AlexHost ofrece servicios profesionales de Email Hosting que se integran perfectamente con aplicaciones autohospedadas como GitLab, proporcionando relé SMTP estable con alta entregabilidad.

Paso 8: Habilitar HTTPS con Let’s Encrypt (Recomendado)

Ejecutar GitLab sobre HTTPS es altamente recomendado para cualquier entorno de producción o de equipo. GitLab tiene soporte integrado para Let’s Encrypt, una autoridad de certificados SSL gratuita y automatizada.

> Importante: Let’s Encrypt requiere que tu nombre de dominio sea accesible públicamente y que el puerto 80 esté abierto en tu servidor. No funcionará con direcciones IP sin procesar.

Abre el archivo de configuración de GitLab:

sudo nano /etc/gitlab/gitlab.rb

Agrega la siguiente configuración:

letsencrypt['enable'] = true
letsencrypt['contact_emails'] = ['your_admin_email@yourdomain.com']
letsencrypt['auto_renew'] = true
letsencrypt['auto_renew_hour'] = 12
letsencrypt['auto_renew_minute'] = 30
letsencrypt['auto_renew_day_of_month'] = "*/7"

Guarda el archivo y reconfigura GitLab:

sudo gitlab-ctl reconfigure

GitLab obtendrá e instalará automáticamente tu certificado SSL, y el ajuste auto_renew asegura que se renueve antes de la expiración sin ninguna intervención manual.

> Alternativa: Si prefieres gestionar certificados SSL de forma independiente o necesitas certificados comodín/multi-dominio, AlexHost ofrece una variedad de Certificados SSL que pueden configurarse manualmente en los ajustes de NGINX de GitLab.

Paso 9: Gestionar servicios de GitLab

GitLab incluye su propia herramienta de gestión de servicios llamada gitlab-ctl. Usa los siguientes comandos para controlar los servicios de GitLab:

Iniciar GitLab

sudo gitlab-ctl start

Detener GitLab

sudo gitlab-ctl stop

Reiniciar GitLab

sudo gitlab-ctl restart

Verificar estado del servicio

sudo gitlab-ctl status

Ver registros en tiempo real

sudo gitlab-ctl tail

Ver registros de un servicio específico (por ejemplo, NGINX)

sudo gitlab-ctl tail nginx

Estos comandos son invaluables para solucionar problemas y mantenimiento rutinario. El comando status mostrará el estado de todos los sub-servicios de GitLab, incluyendo PostgreSQL, Redis, Sidekiq, Puma (servidor web) y NGINX.

Paso 10: Configuración inicial de GitLab para tu organización

Con GitLab instalado y ejecutándose, es hora de configurarlo para las necesidades de tu equipo. Aquí están las áreas clave a configurar a través de la interfaz web de GitLab:

Gestión de usuarios

Navega a Área de administración → Usuarios para crear cuentas de usuario para los miembros de tu equipo. Puedes configurar métodos de autenticación, incluyendo LDAP, OAuth y SAML para inicio de sesión único empresarial.

Grupos y proyectos

• Los grupos te permiten organizar proyectos relacionados y gestionar permisos a escala
• Los proyectos son repositorios individuales con sus propios rastreadores de problemas, wikis y canalizaciones de CI/CD

Canalizaciones de CI/CD

El CI/CD integrado de GitLab es una de sus características más poderosas. Crea un archivo .gitlab-ci.yml en la raíz de tu repositorio para definir canalizaciones automatizadas de compilación, prueba e implementación.

Configuración del repositorio

Configura reglas de protección de ramas, aprobaciones de solicitudes de fusión y flujos de trabajo de revisión de código en la sección Configuración → Repositorio de cada proyecto.

Configuración de copias de seguridad

Configura copias de seguridad automatizadas configurando lo siguiente en /etc/gitlab/gitlab.rb:

gitlab_rails['backup_path'] = "/var/opt/gitlab/backups"
gitlab_rails['backup_keep_time'] = 604800  # Keep backups for 7 days

Ejecuta una copia de seguridad manual en cualquier momento con:

sudo gitlab-backup create

Configuración del firewall

Si tienes UFW (Uncomplicated Firewall) habilitado en tu servidor Ubuntu, asegúrate de permitir tráfico HTTP y HTTPS:

sudo ufw allow http
sudo ufw allow https
sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

Solución de problemas comunes