Cómo instalar GitLab CI en un VPS

Requisitos previos

Prepara un VPS Ubuntu 22.04 o 24.04 dedicado, con SSH, Docker y al menos 2 GB de RAM. Los builds necesitan más CPU, memoria y disco. Debes tener un proyecto o grupo GitLab donde puedas crear runners y una política para merge requests no confiables.

Un runner ejecuta código de los jobs. Trátalo como infraestructura desechable, aleja secretos de producción de pipelines no confiables y no compartas un runner privilegiado entre equipos sin relación.

Qué instala esta guía: Esta guía instala SOLO el agente GitLab Runner, el demonio ligero que ejecuta jobs de CI/CD. Necesita una instancia GitLab EXISTENTE (gitlab.com o autoalojada) para registrarse. Esto NO es el servidor GitLab completo.

Paso 1, Conectarte a tu servidor

Actualiza la máquina y crea la carpeta:

ssh root@SERVER_IP
apt update && apt upgrade -y
apt install -y ca-certificates curl
mkdir -p /opt/gitlab-runner/config
cd /opt/gitlab-runner
chmod 750 /opt/gitlab-runner

Permite SSH. Normalmente el runner no necesita HTTP ni HTTPS públicos. Restringe la salida de red si los jobs no necesitan internet abierto.

Paso 2, Instalar Docker y Docker Compose

Instala Docker Engine y Compose siguiendo las instrucciones oficiales para Ubuntu:

docker --version
docker compose version
systemctl enable --now docker

El executor Docker necesita acceder a Docker. Es potente, así que usa un VPS dedicado y no montes carpetas del host que no hagan falta.

Advertencia: Montar /var/run/docker.sock da al contenedor del runner acceso equivalente a root en el host. Cualquier job de CI puede escapar al host. Usa esta configuración solo para proyectos confiables.

Paso 3, Ejecutar GitLab Runner con Docker Compose

Crea compose.yaml:

services:
  runner:
    image: gitlab/gitlab-runner:alpine
    restart: unless-stopped
    volumes:
      - ./config:/etc/gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock

Arranca el runner:

docker compose config
docker compose pull
docker compose up -d
docker compose ps

Regístralo desde el contenedor:

docker compose exec runner gitlab-runner register

Necesitas un token de registro desde tu proyecto GitLab en Settings > CI/CD > Runners. Los prompts piden:

• La URL de la instancia GitLab (ej. https://gitlab.com)
• El token de registro
• Una descripción y tags para el runner
• El executor: elige Docker
• La imagen base: introduce alpine:latest

Introduce el token de forma interactiva, nunca en un comando versionado.

Paso 4, No necesita proxy inverso

El GitLab Runner no expone un puerto HTTP; se conecta saliente a tu instancia GitLab. No necesita proxy inverso.

En GitLab define tags y estado protected o unprotected según tu modelo de confianza. No permitas que forks no confiables usen un runner con acceso a credenciales de despliegue.

Paso 5, Primer job de CI

Ejecuta un pipeline en GitLab y verifica que el runner lo recoja. Crea un .gitlab-ci.yml mínimo en un proyecto de prueba:

test:
  image: alpine:latest
  script:
    - echo "runner is working"

Publica el archivo y observa el pipeline. Comprueba que el job selecciona el runner correcto, inicia el contenedor y no imprime secretos. Prueba también un fallo y una cancelación.

Si construyes imágenes Docker, usa el executor y el flujo Docker-in-Docker documentados por GitLab para tu modelo de seguridad. Evita privileged mode salvo que sea imprescindible.

Seguridad: El executor Docker da a los jobs de CI acceso completo al daemon de Docker. Para runners multi-proyecto, considera usar máquinas virtuales efímeras o el executor Docker Autoscaler.

Mantenimiento

Actualiza la imagen después de leer las notas de GitLab Runner y prueba primero un proyecto. Guarda la configuración solo si necesitas recrear su identidad y rota las credenciales de registro cuando cambien personas o límites de confianza.

Monitoriza disco por imágenes de jobs, conectividad y jobs fallidos. Limpia caches con una política controlada, no borrando todo el volumen de configuración.