Woodpecker CI y Forgejo: pipeline CI/CD en un VPS

Los servicios CI cloud facturan por minuto de compilación e imponen colas compartidas cuyo tiempo de espera aumenta con el volumen. Cuando los repositorios crecen o los tests se multiplican, la factura supera rápidamente el coste de un VPS dedicado. Alojar Forgejo y Woodpecker CI en el mismo servidor elimina esta latencia de red: el runner lee el código localmente, sin pasar por infraestructura de terceros. También controlas el ciclo de actualizaciones — ningún cambio de precios o política de retención de logs se aplica sin tu consentimiento. Para equipos con restricciones regulatorias o de confidencialidad, esta es una ventaja decisiva: los secretos de integración (claves SSH de despliegue, tokens de acceso a registros) nunca cruzan el perímetro de tu red. Por último, la licencia Apache 2.0 garantiza que el código fuente permanezca auditable y que el proyecto no pueda quedar encerrado tras una oferta comercial exclusiva.

Woodpecker CI puede instalarse en el mismo VPS que Forgejo o en un servidor dedicado. Para ambos servicios combinados, prevé al menos 1 GB de RAM y 2 GB para un uso cómodo con varios repositorios activos en paralelo. En cuanto al software: Docker Engine 24 o superior, Docker Compose v2 (el comando docker compose, no docker-compose), un subdominio dedicado a Woodpecker — por ejemplo ci.your-domain.com — apuntando a la IP del VPS, el puerto 443 abierto para HTTPS y acceso SSH. Forgejo debe ser accesible desde el contenedor de Woodpecker: ya sea a través de la red Docker interna si ambos servicios comparten el mismo host, o mediante su URL pública HTTPS si Woodpecker está en un VPS separado. Woodpecker CI v3 es compatible con Forgejo v1.20 y superior.

Forgejo Actions — disponible desde Forgejo v1.19 en modo experimental, estabilizado progresivamente — replica la sintaxis de GitHub Actions: si tus equipos ya tienen flujos de trabajo .github/workflows/ en producción, la migración es casi transparente. Forgejo Actions es la elección natural para un parque de repositorios que coexiste con GitHub o reutiliza acciones públicas del marketplace. Woodpecker CI responde a necesidades diferentes: su sintaxis YAML es más directa, menos cargada de conceptos heredados de GitHub, y su arquitectura servidor-agente permite desacoplar la forja git del motor CI — útil cuando varios sistemas git necesitan compartir el mismo parque de runners. Woodpecker también es más adecuado para escenarios de compilación multi-arquitectura, donde se quiere enrutar explícitamente un job a un agente ARM o x86. En resumen: elige Forgejo Actions si la compatibilidad con GitHub Actions es prioritaria, y Woodpecker CI si prefieres una sintaxis depurada, un despliegue desacoplado o un parque de runners heterogéneo.

Un archivo .woodpecker.yaml describe una secuencia de pasos ejecutados de forma secuencial en contenedores Docker separados. Cada paso tiene un nombre, una imagen y una lista de comandos. Los pasos pueden compartir el workspace (directorio clonado) a través de un volumen montado automáticamente por Woodpecker. Para un proyecto Node.js, un pipeline básico incluye un paso lint (node:20, npm ci && npm run lint), un paso test (node:20, npm test) y un paso build (node:20, npm run build). Para un proyecto Docker, añade un paso que use el plugin oficial woodpeckerci/plugin-docker-buildx para construir y publicar la imagen en un registro. El disparo condicional se expresa con el bloque when: when: { branch: main, event: push } limita el paso de despliegue a la rama principal en los push directos, excluyendo los pull requests.

Woodpecker distingue dos niveles de secretos: secretos de repositorio (visibles solo en los pipelines del repositorio correspondiente) y secretos globales (accesibles a todos los repositorios, a crear con cuidado). Un secreto se declara en el dashboard — en la sección Secrets del repositorio — y luego se referencia en el pipeline con la sintaxis from_secret. Por ejemplo, una clave SSH de despliegue llamada deploy_key se inyecta en un paso mediante environment: { SSH_KEY: { from_secret: deploy_key } }. Los secretos nunca se pasan a pull requests de forks externos por defecto, evitando la exfiltración por un colaborador malicioso. Para variables no sensibles que deban compartirse entre múltiples repositorios, usa la variable WOODPECKER_ENVIRONMENT a nivel del servidor: los pares CLAVE=valor definidos ahí están disponibles en todos los pipelines sin declaración en el YAML.

Woodpecker CI v3 soporta de forma nativa agentes multi-arquitectura: cada agente anuncia su plataforma al servidor (linux/amd64, linux/arm64, linux/arm/v7) y el servidor enruta los jobs al agente con la plataforma correspondiente. Para declarar un job ARM64, añade platform: linux/arm64 a nivel del pipeline en .woodpecker.yaml. Si dispones de un VPS ARM (Ampere, Raspberry Pi 4 o servidor Hetzner ARM) y un VPS x86_64, despliega un agente en cada uno con el mismo WOODPECKER_AGENT_SECRET y deja que el servidor distribuya las compilaciones. Este mecanismo es útil para compilación cruzada de binarios, pruebas de compatibilidad de imágenes Docker en múltiples arquitecturas o validación de paquetes del sistema. El plugin woodpeckerci/plugin-docker-buildx va más allá y usa QEMU para producir imágenes multi-arch desde un solo agente, pero las compilaciones nativas en la arquitectura objetivo siempre son más rápidas.

Cinco problemas aparecen repetidamente durante la instalación o el uso de Woodpecker CI. Primero: el agente no se conecta al servidor (agent could not auth). Causa más frecuente: WOODPECKER_AGENT_SECRET no es idéntico en ambos servicios. Verifica con docker compose exec woodpecker-server env | grep AGENT_SECRET. Segundo: el login OAuth2 falla con Error while authenticating against OAuth provider. Causa probable: la URL de redirección en la aplicación OAuth2 de Forgejo no coincide exactamente con WOODPECKER_HOST. Comprueba la barra final y la coherencia del esquema HTTPS. Tercero: los pipelines quedan bloqueados en pending. El agente puede estar conectado pero su etiqueta de plataforma no coincide con ningún pipeline; elimina la cláusula platform si no es necesaria. Cuarto: los secretos no se inyectan en los pasos. Los secretos solo se pasan a pipelines activados en ramas internas, nunca en PRs de forks externos por defecto. Verifica que el evento que lo activa sea push o tag. Quinto: tras actualizar a v3.18, faltan logs de compilaciones antiguas. Esta versión incluye una migración del almacenamiento de logs; si la migración se interrumpe, reinicia el contenedor servidor con permisos de escritura en el volumen de datos para que se reanude.

ServOrbit ofrece Woodpecker CI en su marketplace: la aplicación se instala en un VPS Cloud con Docker preconfigurado e IP fija, en pocos clics desde el portal de cliente. Una vez aprovisionado el VPS, basta con apuntar WOODPECKER_FORGEJO_URL a tu forja Forgejo existente e introducir las claves OAuth2 para que los pipelines comiencen a ejecutarse. Esta integración es especialmente útil para agencias o equipos técnicos que quieren aislar el motor CI del servidor de forja: Forgejo en un VPS, Woodpecker en un segundo, comunicándose vía HTTPS. Los recursos del VPS son ajustables en cualquier momento desde el portal de cliente — añadir RAM o vCPU sin reinstalar — lo que permite dimensionar el parque de runners según la carga real de compilaciones.

Forgejo gestiona el código, los issues y las revisiones de pull requests; Woodpecker CI orquesta los pipelines de test y despliegue. Los dos se comunican mediante OAuth2 y webhooks en tu propia red, sin dependencia de GitHub, GitLab o ningún servicio de integración cloud. Esta stack auto-alojada responde a las restricciones de soberanía de las agencias y equipos técnicos que no quieren que su propiedad intelectual o sus secretos de integración transiten por plataformas externas. Con Woodpecker CI v3 y Forgejo v1.20 o superior, dispones de un entorno de desarrollo completo — forja git, CI/CD, registro Docker si es necesario — completamente bajo tu control, en uno o dos VPS, con un coste mensual predecible y sin cuota de minutos de compilación.