← Volver al listado de tecnologías ← Índice de Forgejo

Configurar Forgejo Runner

Por: Artiko
forgejorunnerci-cddockerdevops

Capitulo 15: Configurar Forgejo Runner

El Forgejo Runner es el proceso que ejecuta los jobs definidos en los workflows. Sin al menos un runner activo, los workflows quedaran en estado pendiente indefinidamente.

Obtener el token de registro

Antes de instalar el runner necesitas un token que lo autentique ante el servidor Forgejo. Existen tres niveles de registro:

A nivel de instancia (recomendado para administradores)

Navega a:

Site Administration > Runners > Create Runner

El token generado permite que el runner acepte jobs de cualquier repositorio de la instancia.

A nivel de organizacion

Desde la configuracion de la organizacion:

Organization Settings > Runners > Create Runner

El runner solo aceptara jobs de repositorios dentro de esa organizacion.

A nivel de repositorio

Desde la configuracion del repositorio:

Repository Settings > Runners > Create Runner

El runner solo acepta jobs de ese repositorio especifico.

Copia el token generado, lo necesitaras en el siguiente paso.

Runner en el mismo servidor vs servidor separado

Antes de instalar, decide donde va a correr el runner:

Mismo servidor que Forgejo

Ventajas: configuracion mas simple, sin latencia de red entre runner y servidor. Desventajas: los jobs compiten por recursos con el propio Forgejo, un job intensivo puede afectar la disponibilidad del servidor.

Servidor separado

Ventajas: aislamiento de recursos, el servidor Forgejo no se ve afectado por los jobs, puede escalar independientemente. Desventajas: requiere que el runner tenga acceso de red al servidor Forgejo (puerto HTTP/HTTPS).

Para instancias de produccion con carga real, se recomienda un servidor separado.

Instalacion con Docker Compose

La forma mas sencilla de instalar el runner es usando Docker. Crea un archivo docker-compose.yml para el runner:

services:
  runner:
    image: code.forgejo.org/forgejo/runner:6
    container_name: forgejo-runner
    restart: unless-stopped
    environment:
      FORGEJO_INSTANCE: https://git.ejemplo.com
      FORGEJO_RUNNER_REGISTRATION_TOKEN: "TU_TOKEN_AQUI"
      FORGEJO_RUNNER_NAME: "runner-principal"
      FORGEJO_RUNNER_LABELS: "ubuntu-latest:docker://node:20,self-hosted:host"
    volumes:
      - runner_data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    network_mode: bridge

volumes:
  runner_data:

Puntos importantes de esta configuracion:

Entender las labels del runner

Las labels determinan que jobs puede ejecutar este runner. En el workflow, el campo runs-on debe coincidir con alguna label del runner.

El formato de una label es:

nombre-label:tipo://imagen-o-shell

Ejemplos comunes:

ubuntu-latest:docker://ubuntu:22.04
node20:docker://node:20-alpine
self-hosted:host
docker:docker://docker:dind

Si un workflow pide runs-on: ubuntu-latest y el runner tiene la label ubuntu-latest:docker://ubuntu:22.04, el runner acepta ese job y lo ejecuta dentro de un contenedor Ubuntu 22.04.

Registrar el runner manualmente

Si prefieres registrar el runner de forma interactiva en lugar de usar variables de entorno:

# Iniciar el contenedor sin auto-registro
docker run -d \
  --name forgejo-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v runner_data:/data \
  code.forgejo.org/forgejo/runner:6 \
  forgejo-runner daemon

# Registrar de forma interactiva
docker exec -it forgejo-runner forgejo-runner register \
  --instance https://git.ejemplo.com \
  --token TU_TOKEN \
  --name runner-principal \
  --labels ubuntu-latest:docker://ubuntu:22.04

El proceso de registro genera un archivo de configuracion en el volumen de datos del runner.

Archivo config.yaml del runner

El runner acepta un archivo de configuracion config.yaml con opciones avanzadas. Para usarlo, montalo como volumen:

services:
  runner:
    image: code.forgejo.org/forgejo/runner:6
    volumes:
      - ./runner-config.yaml:/data/config.yaml
      - /var/run/docker.sock:/var/run/docker.sock

Ejemplo de runner-config.yaml:

runner:
  capacity: 3          # Jobs paralelos maximos
  timeout: 3h          # Timeout maximo por job
  insecure: false      # No verificar TLS (no recomendado en produccion)

cache:
  enabled: true
  dir: ""              # Directorio de cache, vacio = directorio temporal

container:
  network: "bridge"    # Red Docker para los contenedores de jobs
  privileged: false    # No ejecutar contenedores con privilegios
  options: ""          # Opciones adicionales para docker run

La opcion capacity es especialmente importante: define cuantos jobs puede ejecutar el runner en paralelo. Ajustala segun los recursos disponibles.

Iniciar el runner

Con el docker-compose.yml listo:

docker compose up -d

Verificar que el proceso esta corriendo:

docker compose logs -f runner

Deberias ver mensajes indicando que el runner se registro correctamente y esta esperando jobs:

time="..." level=info msg="Runner registered successfully."
time="..." level=info msg="Waiting for tasks..."

Verificar en la interfaz de Forgejo

Navega a la misma seccion donde obtuviste el token de registro. El runner deberia aparecer en la lista con estado Online (punto verde).

Si aparece Offline, revisa:

  1. Que el runner tenga conectividad de red al servidor Forgejo
  2. Que el token sea correcto y no haya expirado
  3. Los logs del runner con docker compose logs runner

Actualizar el runner

Para actualizar a una nueva version del runner:

docker compose pull runner
docker compose up -d runner

Consulta las notas de version en code.forgejo.org/forgejo/runner antes de actualizar en produccion para verificar posibles cambios de configuracion.

Siguiente: Capitulo 16: Escribir Workflows —>

← Volver al listado de tecnologías ← Índice de Forgejo