Cómo instalar GitLab en un VPS

Requisitos reales, no los del folleto

La documentación oficial de GitLab establece como referencia 8 vCPU y 16 GB de RAM para una instalación de un solo nodo. Es la cifra que GitLab considera segura para un uso normal con varios usuarios y pipelines activos. También indica que puede funcionar en entornos con 8 GB si se aplica una configuración específica de memoria limitada.

Tres advertencias que ahorran disgustos. Primera: GitLab desaconseja instancias con CPU de rendimiento variable ("burstable"), porque el rendimiento se vuelve impredecible. Segunda: el nodo de aplicación necesita unos 40 GB de disco antes de contar el tamaño de tus repositorios, que se suman aparte. Tercera: la documentación recomienda almacenamiento SSD, especialmente por la carga de entrada y salida de Gitaly, el servicio que sirve los repositorios; un disco NVMe marca una diferencia perceptible.

Antes de instalar, mira lo que tienes:

nproc
free -h
df -h /
lsb_release -a

CE, EE y cuál instalar

Los dos paquetes contienen el mismo producto base; la diferencia es que gitlab-ee admite activar una licencia después sin reinstalar. Sin licencia, gitlab-ee funciona exactamente en el nivel Free, con las mismas funciones que CE.

• Instala gitlab-ce si quieres una instalación estrictamente de código abierto bajo licencia MIT.
• Instala gitlab-ee si existe alguna posibilidad de comprar una licencia más adelante y prefieres no migrar entonces.

Ninguna de las dos opciones cambia el consumo de recursos ni el procedimiento de esta guía.

Preparar el servidor

GitLab necesita un dominio con registro A ya resuelto antes de instalar, porque el certificado se solicita durante el proceso. Configúralo primero y verifícalo.

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl openssh-server ca-certificates tzdata perl
dig +short gitlab.ejemplo.com A

Abre los puertos necesarios:

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

El 22 lo usarán los desarrolladores para git push por SSH, además de tu propia administración. Si ya cambiaste el puerto de SSH del servidor, tenlo presente: GitLab mostrará las URLs de clonado con el puerto que le indiques en la configuración, no con el que asuma.

Si el VPS tiene 8 GB o menos, añade swap antes de instalar. GitLab hace un pico considerable durante la reconfiguración inicial y sin swap ese pico termina en un proceso muerto:

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

La guía de configurar swap en Ubuntu explica cuánta conviene según la RAM.

Instalar GitLab desde el repositorio oficial

GitLab publica su propio repositorio de paquetes; el script oficial lo añade y configura las claves.

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

Un script canalizado a bash se ejecuta con privilegios elevados. Si tu política lo exige, descárgalo e inspecciónalo antes de ejecutarlo. Después, instala indicando la URL externa:

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

Escribir la URL con https:// hace que GitLab solicite automáticamente un certificado de Let's Encrypt durante la instalación. La instalación tarda entre 5 y 15 minutos: descarga cerca de un gigabyte, ejecuta las recetas de configuración y arranca una docena de servicios.

Recupera la contraseña inicial:

sudo cat /etc/gitlab/initial_root_password

Ese archivo se borra automáticamente a las 24 horas. Entra en https://gitlab.ejemplo.com como usuario root, cambia la contraseña de inmediato y guárdala en tu gestor de contraseñas.

Lo segundo que debes hacer, antes que cualquier otra cosa: desactivar el registro público. Ve a Admin → Settings → General → Sign-up restrictions y desmarca "Sign-up enabled". Un GitLab abierto en internet con registro libre se llena de cuentas automatizadas que usan tus pipelines para minar criptomonedas. Es un problema real y frecuente.

Ajustar el consumo de memoria

GitLab documenta oficialmente una configuración para entornos con memoria limitada, y en un VPS de 8 GB marca la diferencia entre usable e inservible. Edita /etc/gitlab/gitlab.rb:

# Puma en modo de proceso único: ahorra entre 100 y 400 MB
puma['worker_processes'] = 0

# Menos trabajos simultáneos en segundo plano (por defecto 20)
sidekiq['concurrency'] = 10

# Prometheus no es necesario para que GitLab funcione
prometheus_monitoring['enable'] = false

# Devolver memoria al sistema con más frecuencia
gitlab_rails['env'] = {
  'MALLOC_CONF' => 'dirty_decay_ms:1000,muzzy_decay_ms:1000'
}

Aplica los cambios:

sudo gitlab-ctl reconfigure
sudo gitlab-ctl status
free -h

Qué pierdes con cada ajuste, para que decidas con criterio: el modo de proceso único de Puma reduce la concurrencia de la interfaz web (se nota con muchos usuarios simultáneos); bajar la concurrencia de Sidekiq hace que las tareas en segundo plano se encolen más; desactivar Prometheus elimina los gráficos internos de monitoreo, no la funcionalidad de GitLab.

Si el servidor tiene 16 GB, no apliques nada de esto: estarás limitando el rendimiento sin necesidad.

Configurar el correo

Sin SMTP, GitLab no envía invitaciones, notificaciones de merge request ni recuperación de contraseña. En /etc/gitlab/gitlab.rb:

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.tuproveedor.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "[email protected]"
gitlab_rails['smtp_password'] = "CLAVE"
gitlab_rails['smtp_domain'] = "ejemplo.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['gitlab_email_from'] = "[email protected]"

sudo gitlab-ctl reconfigure
sudo gitlab-rails console

Y dentro de la consola:

Notify.test_email('[email protected]', 'Prueba', 'Funciona').deliver_now

Usa un servicio transaccional real con SPF y DKIM configurados; la guía de correo que cae en spam cubre esos registros.

Instalar y registrar un GitLab Runner

El Runner es el proceso que ejecuta los pipelines, y ponerlo en el mismo VPS que GitLab es la causa número uno de instancias que se caen durante un build. Un npm install o una compilación de imagen Docker puede consumir varios gigabytes de memoria; si compite con GitLab, gana el sistema operativo matando procesos.

Si aun así lo instalas en el mismo servidor (es aceptable para uso personal), hazlo así:

curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo apt install -y gitlab-runner

Genera un token de autenticación en Settings → CI/CD → Runners del proyecto o grupo, y registra:

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.ejemplo.com" \
  --token "glrt-TU_TOKEN" \
  --executor "docker" \
  --docker-image "alpine:latest" \
  --description "runner-principal"

Comprueba:

sudo gitlab-runner list
sudo gitlab-runner verify

Limita los recursos que puede tomar un trabajo editando /etc/gitlab-runner/config.toml, empezando por concurrent = 1 para que no se ejecuten dos builds a la vez. Si trabajas con Docker en los pipelines, la guía de Docker en un VPS explica la configuración base.

Backups: el archivo no basta

gitlab-backup create genera un archivo con la base, los repositorios y los adjuntos, pero deliberadamente no incluye los secretos. Ese detalle arruina restauraciones enteras y conviene grabárselo.

sudo gitlab-backup create
ls -lh /var/opt/gitlab/backups/

Copia además, y por separado, estos dos archivos:

sudo cp /etc/gitlab/gitlab-secrets.json /ruta/segura/
sudo cp /etc/gitlab/gitlab.rb /ruta/segura/

gitlab-secrets.json contiene las claves con las que GitLab cifró las variables de CI, los tokens de integración y los secretos de dos factores. Si restauras el archivo de backup sin él, la instancia arranca pero todos esos datos quedan ilegibles y no hay forma de recuperarlos.

Automatiza el proceso y saca las copias del VPS:

0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON=1

Después, sincroniza el directorio de backups y los secretos hacia otro servidor con rsync, como describe la guía de backups con rsync y cron. Y prueba la restauración completa en un VPS distinto al menos una vez: un backup sin ensayo es una suposición.

Migrar desde GitHub

GitLab incluye un importador que trae repositorios, issues, pull requests, wikis, etiquetas y milestones usando un token de acceso personal de GitHub. Ve a Nuevo proyecto → Importar proyecto → GitHub, pega el token y selecciona los repositorios.

Lo que no migra: los flujos de trabajo de GitHub Actions. La sintaxis de GitLab CI es distinta y hay que reescribirlos. Un .gitlab-ci.yml mínimo se ve así:

stages:
  - test
  - build

test:
  stage: test
  image: node:22-alpine
  script:
    - npm ci
    - npm test

build:
  stage: build
  image: node:22-alpine
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
  only:
    - main

Antes de apagar nada en GitHub, comprueba en GitLab que el historial completo llegó (git log en un clon nuevo), que los issues conservan sus comentarios y que un pipeline de prueba pasa.

Problemas frecuentes

Un 502 en GitLab suele ser Puma sin arrancar; la guía del error 502 Bad Gateway ayuda a separar la capa que falla.