Hay buenas razones para sacar tus repos personales de GitHub. No por ningún drama (GitHub está bien), sino para tener control total de tus runners de CI, tus secretos y tus artefactos de build en el mismo hardware donde corre el resto de tu homelab. Forgejo es el destino obvio, y Forgejo Actions maduró al punto de que la migración es casi indolora: copias tu carpeta .github/workflows a .forgejo/workflows, conectas un runner y listo.
Esta guía muestra el setup completo: Forgejo en un LXC de Proxmox con Forgejo Actions activado, un LXC aparte para el runner con Docker y un pipeline de CI real que compila y publica. Un equipo como el Beelink SER8 con Ryzen 7 8845HS es más que suficiente para correrlo todo.
Por qué Forgejo y no Gitea (en 2026)
Un baño de realidad antes de pasar una tarde instalando software del que te vas a arrepentir. Gitea y Forgejo siguen siendo casi idénticos a nivel de código: Forgejo nació como fork a finales de 2022 por preocupaciones de gobernanza cuando Gitea Ltd. se separó como empresa con fines de lucro. Tres años después, se han distanciado lo suficiente como para que la elección importe.
Los puntos fuertes de Forgejo en 2026: gobernanza sin fines de lucro bajo Codeberg e.V., licencia GPL (Gitea es MIT), backports de seguridad mensuales y Forgejo Actions recibe funciones antes que Gitea Actions. La propuesta de Gitea es su plan empresarial (sincronización con la nube, proxy de paquetes, funciones para organizaciones), que no importa si autoalojas para ti o para un equipo pequeño. Para un homelab, Forgejo gana por principios y por ritmo de desarrollo.
Si ya usas Gitea, no migres solo por migrar. El camino de exportar/importar funciona pero no es perfecto, y la experiencia del día a día es idéntica. Elige Forgejo para instalaciones nuevas.
La arquitectura
Dos LXC en Proxmox, comunicándose por el bridge de LXC:
- forgejo-lxc: contenedor Debian 12 sin privilegios, 2 vCPU, 4 GB de RAM, 32 GB de disco. Corre Forgejo + PostgreSQL.
- forgejo-runner-lxc: contenedor Debian 12 con privilegios (nesting=1, keyctl=1), 4 vCPU, 8 GB de RAM, 64 GB de disco. Corre el runner de Forgejo Actions y Docker.
¿Por qué separar el runner en su propio LXC? Por dos razones. Primero, el runner ejecuta código arbitrario de tus repos: mejor mantener ese riesgo aislado de la base de datos. Segundo, Docker dentro de LXC requiere un contenedor con privilegios y nesting activado, y no quieres que tu servidor de git necesite esos permisos.
Si lo vas a correr en un mini PC dedicado en lugar de un host de Proxmox potente, un mini PC con N100 como el Beelink Mini S12 maneja bien el contenedor de Forgejo, pero para el runner conviene algo con más núcleos, como el GMKtec NucBox K8 o el SER8 mencionado arriba.
Instalación de Forgejo
Aquí instalamos Forgejo como binario bajo systemd, no con Docker. El binario es más simple de respaldar y actualizar, y la diferencia de consumo frente a Docker se nota en LXC pequeños.
# In forgejo-lxc, as root
apt update && apt install -y postgresql-15 git curl
useradd --system --create-home --home-dir /var/lib/forgejo \
--shell /bin/bash --comment "Forgejo" git
# Create the database
sudo -u postgres psql -c "CREATE USER forgejo WITH PASSWORD 'changeme';"
sudo -u postgres psql -c "CREATE DATABASE forgejo OWNER forgejo;"
# Download the latest binary (check forgejo.org/releases for current)
FORGEJO_VERSION=10.0.1
curl -fsSL -o /usr/local/bin/forgejo \
https://codeberg.org/forgejo/forgejo/releases/download/v${FORGEJO_VERSION}/forgejo-${FORGEJO_VERSION}-linux-amd64
chmod +x /usr/local/bin/forgejo
# Directory layout
mkdir -p /var/lib/forgejo/{custom,data,log}
chown -R git:git /var/lib/forgejo
chmod -R 750 /var/lib/forgejo
mkdir -p /etc/forgejo && chown root:git /etc/forgejo && chmod 770 /etc/forgejoCrea una unidad de systemd en /etc/systemd/system/forgejo.service (la documentación de Forgejo tiene una de referencia limpia) y luego systemctl enable --now forgejo. Entra a http://forgejo-lxc:3000, corre el instalador y crea tu cuenta de administrador.
Dos ajustes que cambiar en /etc/forgejo/app.ini después de instalar:
[server]
ROOT_URL = https://git.yourdomain.local/
DOMAIN = git.yourdomain.local
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = githubDEFAULT_ACTIONS_URL = github es lo que hace que la mayoría de las GitHub Actions existentes funcionen sin cambios: cuando un workflow hace referencia a uses: actions/checkout@v4, Forgejo la descarga de github.com en lugar de esperar un espejo local. Reinicia Forgejo. Ya tienes una forja de código autoalojada con CI.
El runner de Forgejo Actions
Aquí es donde está lo interesante. El runner es un binario de Go separado que consulta a Forgejo por trabajos y los ejecuta, por defecto en contenedores Docker, que es justo lo que quieres.
Dentro de forgejo-runner-lxc (después de activar nesting en la configuración del LXC e instalar Docker):
RUNNER_VERSION=6.2.2
curl -fsSL -o /usr/local/bin/forgejo-runner \
https://code.forgejo.org/forgejo/runner/releases/download/v${RUNNER_VERSION}/forgejo-runner-${RUNNER_VERSION}-linux-amd64
chmod +x /usr/local/bin/forgejo-runner
useradd --system --create-home --home-dir /var/lib/forgejo-runner \
--shell /bin/bash forgejo-runner
usermod -aG docker forgejo-runner
# Generate the runner config
sudo -u forgejo-runner forgejo-runner generate-config > \
/var/lib/forgejo-runner/config.ymlEdita /var/lib/forgejo-runner/config.yml y cambia algunos valores por defecto:
runner:
capacity: 2 # how many jobs to run concurrently
timeout: 30m
labels:
- "ubuntu-latest:docker://node:20-bookworm"
- "ubuntu-22.04:docker://node:20-bookworm"
- "self-hosted:host"
cache:
enabled: true
dir: "/var/lib/forgejo-runner/cache"
container:
network: "bridge"
privileged: false
options: ""Obtén un token de registro en el panel de administración de Forgejo, en Site Administration → Actions → Runners → "Create new Runner", y registra el runner:
sudo -u forgejo-runner forgejo-runner register \
--no-interactive \
--instance http://forgejo-lxc:3000 \
--token <your-token> \
--name "homelab-runner-1" \
--labels "ubuntu-latest,ubuntu-22.04,self-hosted"Envuélvelo en una unidad de systemd e inícialo. En unos 10 segundos deberías ver el runner como "online" en el panel de administración de Forgejo.
Un workflow real
Este es un .forgejo/workflows/ci.yml mínimo para un proyecto de Node, del tipo que realmente pone a trabajar al runner:
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- run: npm ci
- run: npm run lint
- run: npm test
build-and-push:
needs: test
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Login to Forgejo registry
run: echo "${{ secrets.REGISTRY_TOKEN }}" | \
docker login forgejo-lxc:3000 -u ${{ github.actor }} --password-stdin
- run: docker build -t forgejo-lxc:3000/ricardo/myapp:${{ github.sha }} .
- run: docker push forgejo-lxc:3000/ricardo/myapp:${{ github.sha }}El registro de contenedores de Forgejo viene activado por defecto y vive en el mismo hostname que la interfaz web: no necesitas un Harbor o Nexus aparte. Para la mayoría de los homelabs es suficiente; el registro maneja imágenes OCI, npm, Maven y una docena de formatos más de serie.
Los detalles que nadie menciona
Los fallos de caché son comunes. La caché de actions de Forgejo es local a cada runner. Si tienes varios runners, los trabajos que caen en runners distintos no comparten caché. Con un solo runner no importa; si escalas, revisa el ajuste cache_proxy y un backend compartido compatible con S3, como MinIO corriendo en un Synology DS224+.
Docker dentro de Docker es complicado en LXC. El runner levanta contenedores para cada trabajo, lo que funciona bien hasta que un trabajo intenta levantar a su vez un contenedor (testcontainers, kind, etc.). La solución es nesting=1 en el LXC y usar contenedores --privileged en tus trabajos, pero a esas alturas te conviene más correr el runner en una VM completa. Una VM con Ubuntu Server aparte para los trabajos que necesitan DinD real es la opción más limpia.
Los secretos son por repo o por organización. A diferencia de GitHub, no hay secretos por entorno de serie (está en camino, pero no en la 10.x). Planifica tu estrategia de secretos: por ejemplo, llaves de despliegue por repo y credenciales de infraestructura a nivel de organización.
No expongas el runner. Exponer la interfaz web de Forgejo con un Cloudflare Tunnel o un proxy inverso está bien. El runner nunca debería ser accesible desde fuera de tu red local, y no necesita serlo: el runner se conecta hacia Forgejo, no al revés.
Los respaldos importan. Forgejo está a un comando forgejo dump de un tarball limpio, pero la caché del runner y los volúmenes de Docker no entran en ese volcado. Una buena estrategia es correr Restic cada noche contra un bucket de Backblaze B2 para la carpeta de datos de Forgejo y no respaldar el runner: se puede recrear desde la configuración.
Notas sobre hardware
No necesitas mucho. Forgejo consume ~150 MB de RAM en reposo y el runner solo usa memoria mientras hay trabajos activos. El cuello de botella del CI casi siempre es la E/S (clones de git, npm install, caché de capas de Docker), así que prioriza un NVMe rápido antes que más núcleos.
Un solo WD Black SN850X de 2 TB en un host de Proxmox te da margen para Forgejo, una docena de LXC más y la caché de CI sin saturarse. Si vas a armar un equipo dedicado de git/CI, el Beelink SER8 o el Minisforum UM790 Pro son el punto ideal: 8 núcleos, 32 GB de DDR5 y espacio para dos NVMe.
Para respaldos, un Synology DS923+ en la misma VLAN te da un destino para Restic sin factura de la nube, aunque conviene mantener B2 como segundo nivel fuera de casa. La RAM importa menos de lo que crees: un LXC de Forgejo con 4 GB tiene margen de sobra.
Cómo migrar desde GitHub
Para cada repo que quieras mover:
- Crea un repo vacío equivalente en Forgejo
git remote set-url origin http://forgejo-lxc:3000/ricardo/myrepo.git && git push --mirror- Copia
.github/workflows/*.ymla.forgejo/workflows/*.yml(es literalmente renombrar la carpeta, sin cambios de sintaxis en ~95% de los workflows) - Reemplaza las referencias
actions/cache@v4porhttps://code.forgejo.org/actions/cache@v4si quieres caché propia; si no, el fallback a GitHub funciona - Configura los secretos en los ajustes del repo nuevo
- Haz push y mira cómo el runner toma el trabajo
Calcula unos 15 minutos por repo. Lo que suele tomar más tiempo es reconfigurar herramientas como Renovate para que apunten a la nueva URL de Forgejo.
¿Vale la pena?
Si ya tienes un homelab funcionando y subes código con frecuencia, sí. Un argumento fuerte son los minutos de build: es fácil agotar el plan gratis de GitHub con builds de contenedores de proyectos que solo te importan a ti. Correr el CI en hardware que ya tienes es prácticamente gratis, y un runner local suele ser notablemente más rápido que los runners alojados de GitHub (sin arranque en frío, sin cola de espera y con caché de capas persistente).
Si usas git de forma casual y tienes tres repos, quédate en GitHub. Forgejo vale el esfuerzo operativo solo cuando chocas con una limitación real de GitHub: facturación, privacidad, tráfico de red o cumplimiento normativo.
En un homelab que ya tiene Proxmox, Tailscale y una estrategia de respaldos que funciona, este es el siguiente paso natural. Una vez configurado, prácticamente solo tendrás que tocarlo para actualizar el binario de Forgejo de vez en cuando. Ese es el nivel que debería cumplir tu stack autoalojado.
Aviso: este artículo contiene enlaces de afiliado. Si compras a través de ellos, puedo ganar una pequeña comisión sin costo extra para ti.
¿Quieres algo así para tu negocio?
Instalo infraestructura privada y autoalojada en Proxmox: IA, automatización y herramientas internas en hardware que es tuyo, documentado y entregado. Ver el stack de IA privada →
¿No sabes qué necesitas? Agenda una llamada gratis.