Guía práctica para ejecutar tu propio Forgejo Runner en Codeberg

¿Por qué usar tu propio runner de CI/CD?

Si estás buscando alternativas a GitHub, Codeberg es una opción muy interesante. Se basa en Forgejo y lo gestiona una organización sin ánimo de lucro, lo que lo convierte en una plataforma centrada en la privacidad y la comunidad. Sin embargo, como cualquier servicio que depende de recursos compartidos, su infraestructura de runners tiene ciertas limitaciones.

La solución es montar tu propio runner de Forgejo. Lo mejor es que estos runners se conectan hacia afuera, por lo que funcionan sin problemas en un VPS, en un servidor en casa o incluso en un portátil. No necesitas abrir puertos ni configurar reglas de firewall.

Cómo funciona la arquitectura

Antes de entrar en los detalles, vale la pena entender lo que vamos a construir. Un runner de Forgejo es un proceso que recibe tareas desde Codeberg y las ejecuta. Para mantener la seguridad, lo aislaremos del sistema anfitrión mediante Docker-in-Docker (DinD). De esta forma, el runner crea contenedores sin tocar el daemon Docker de tu máquina.

Configuración con Docker Compose

El setup básico consiste en dos contenedores:

version: '3.8'

services:
  docker-in-docker:
    image: docker:dind
    container_name: 'docker_dind'
    privileged: 'true'
    command: ['dockerd', '-H', 'tcp://0.0.0.0:2375', '--tls=false']
    restart: 'unless-stopped'

  runner:
    image: 'data.forgejo.org/forgejo/runner:12'
    links:
      - docker-in-docker
    depends_on:
      docker-in-docker:
        condition: service_started
    container_name: 'runner'
    environment:
      DOCKER_HOST: tcp://docker-in-docker:2375
    user: 1001:1001
    volumes:
      - ./data:/data
    restart: 'unless-stopped'
    command: 'forgejo-runner daemon --config runner-config.yml'

El primer contenedor proporciona un entorno Docker aislado. El segundo es el runner que usa ese entorno para ejecutar las tareas.

Preparación del sistema

Antes de lanzar los contenedores, hay que preparar el sistema de archivos. Te recomiendo crear una carpeta en /opt/forgejo-runner y ejecutar:

cd /opt/forgejo-runner
mkdir -p data/.cache
chown -R 1001:1001 data
chmod 775 data/.cache
chmod g+s data/.cache

A continuación, generamos el archivo de configuración por defecto:

sudo sh -c 'docker run --rm data.forgejo.org/forgejo/runner:12 forgejo-runner generate-config > data/runner-config.yml'

Este documento es bastante completo y puedes ajustarlo según tus necesidades.

Cómo registrar el runner en Codeberg

Para conectar tu runner con Codeberg, entra en tu cuenta o en la organización y ve a Actions → Runners. Haz clic en "Create new runner", ponle un nombre y una descripción opcional.

En ese momento, Codeberg genera un UUID y un token. Apúntalos en cuanto aparezcan, ya que no los volverás a ver sin reiniciarlos.

Codeberg también te muestra el fragmento de YAML que necesitas incluir en tu configuración.

Configuración de etiquetas y capacidad

En el archivo runner-config.yml debes hacer dos ajustes importantes:

1. Añadir las credenciales Copia el UUID y el token que te dio Codeberg en la sección correspondiente.

2. Definir las etiquetas Las etiquetas son el mecanismo que usa Codeberg para asignar tareas a los runners. Escriben en un formato específico: [Etiqueta del Workflow]:[Método]:[Entorno]

Por ejemplo:

labels: 
  - 'ubuntu-latest:docker://node:20-bookworm'
  - 'ubuntu-22.04:docker://node:20-bookworm'
  - 'ubuntu-24.04:docker://node:22-bookworm'

当一个 workflow specifies runs-on: ubuntu-latest, Codeberg busca el runner con esa etiqueta. 这是一种简单的分配机制.

Opcional: Aumentar la capacidad La configuración por defecto permite que el runner maneje una tarea a la vez. 如果你有足够 de recursos, puedes aumentar el valor de capacity para ejecutar varias tareas simultáneamente. Te recomiendo empezar con 4.

Cómo ponerlo en marcha

Una vez listo el archivo de configuración, puedes lanzar el sistema:

docker-compose up -d

Luego puedes seguir los logs para confirmar que el runner se ha registrado correctamente:

docker-compose logs -f runner

你会看到确认消息。之后任何 workflow que use你的标签将由你的 self-hosted runner执行。

Ventajas que notarás de inmediato

Al tener tu runner propio, obtendrás:

• Ejecución de tareas más rápida, sin esperas en la cola
• Control total sobre el entorno y las dependencias
• Ahorro de costes mientras apoyas a Codeberg
• Mayor privacidad, al mantener los logs en tu infraestructura
• Flexibilidad para crecer según tus necesidades

Conclusión

Montar un runner de Forgejo en casa o en tu VPS es un proyecto que da resultados desde el primer día. Es sencillo de configurar y puede crecer con tu equipo. Además, al reducir la carga sobre Codeberg's shared runners, estás contribuyendo directamente a el open-source ecosystem.

Si ya usas Codeberg, esto es el paso natural. Si todavía estás en GitHub y estás buscando alternativas, tener un CI/CD fiable es uno de los factores clave para la decisión.