Reemplazar GitHub Actions con Woodpecker CI en VPS

Hasta 2025, los repositorios privados tenían una cuota mensual de minutos incluidos. El 16 de diciembre de 2025, GitHub anunció precios por minuto para el uso de runners — incluidos los self-hosted runners que corren en tus propias máquinas. La discusión de GitHub #182089 (diciembre de 2025, 72 votos) resume la preocupación: los equipos habrían pagado a GitHub por orquestar un trabajo corriendo en su propia infraestructura, a 0,002 $ por minuto.

Ante una reacción masiva de la comunidad, GitHub suspendió la tarificación en menos de 48 horas. A 1 de septiembre de 2026, los runners self-hosted en repos privados siguen siendo gratuitos — la medida nunca llegó a aplicarse. Pero el anuncio dejó al descubierto una dependencia estructural: GitHub puede cambiar sus condiciones en cualquier momento. Trasladar toda la cadena CI/CD a una forja self-hosted es la manera de eliminar esa incertidumbre. Woodpecker CI está diseñado exactamente para esto: un motor de pipeline ligero, open source (Apache 2.0), que se instala junto a Gitea o Forgejo y no tiene contador de minutos.

Para desplegar Woodpecker CI cómodamente, verifica los siguientes requisitos.

VPS: 1 vCPU y 1 GB de RAM son suficientes para el servidor Woodpecker, un agente y una forja Gitea o Forgejo ligera. Cuenta con 2 GB si ejecutas varios builds en paralelo o tus jobs construyen imágenes Docker.

Software: Docker y Docker Compose deben estar instalados. Si partes de un VPS limpio, la guía Empezar con Docker en VPS cubre este paso.

Forja git: Woodpecker CI utiliza OAuth2 para la autenticación. Necesitas una instancia de Gitea o Forgejo ya en marcha y accesible vía HTTPS. Las guías Alojar Gitea y Alojar Forgejo detallan esta instalación.

Dominio: prepara un subdominio dedicado para Woodpecker — por ejemplo ci.tu-dominio.com — apuntando a la IP de tu VPS con el puerto 443 abierto. Este subdominio sirve como WOODPECKER_HOST y como URL de redirección OAuth2.

Woodpecker CI tiene su propia sintaxis YAML — no es compatible con GitHub Actions. La buena noticia: es más corta. Aquí tienes la migración de un workflow clásico de Node.js.

Antes — .github/workflows/ci.yml:

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test

Después — .woodpecker.yml:

steps:
  - name: test
    image: node:20
    commands:
      - npm ci
      - npm test

Diferencias clave: Woodpecker usa directamente una imagen Docker como entorno de ejecución (no necesita setup-node), y cada paso es un servicio de contenedor. La acción checkout es implícita — Woodpecker clona automáticamente el repositorio en el espacio de trabajo compartido entre los pasos.

El agente no aparece en el dashboard. Verifica que WOODPECKER_AGENT_SECRET sea idéntico en ambos servicios del docker-compose.yml. Si modificaste el .env después del primer arranque, reinicia con docker compose down && docker compose up -d.

El inicio de sesión OAuth2 falla. La URL de redirección registrada en Gitea debe coincidir exactamente con https://ci.tu-dominio.com/authorize. Una barra final, un error tipográfico o HTTP en lugar de HTTPS son suficientes para bloquear el flujo OAuth2. Comprueba también que WOODPECKER_GITEA_URL apunte a la URL pública de tu Gitea.

El webhook no se dispara. Abre el repositorio en Gitea → Configuración → Webhooks y verifica que el webhook de Woodpecker esté presente y que las entregas recientes no tengan errores 4xx.

Los builds fallan por falta de memoria. El servidor y el agente de Woodpecker consumen menos de 50 MB en reposo — pero cada paso de build lanza un contenedor Docker adicional. En un VPS de 1 GB, limita los builds concurrentes añadiendo WOODPECKER_MAX_PROCS=2 al entorno del servicio woodpecker-agent.

Una vez que el pipeline base funciona, varias optimizaciones valen la pena.

Multi-runner. Añade un segundo servicio woodpecker-agent a tu docker-compose.yml (misma imagen, mismo WOODPECKER_AGENT_SECRET) para paralelizar los builds.

Caché Docker entre builds. Monta un volumen Docker en el agente y activa la caché de capas Docker para evitar volver a descargar las imágenes en cada build.

Notificaciones. Woodpecker puede notificar un canal de mensajería en cada build — Matrix, Slack, Telegram y Mattermost.

Pipeline condicional. La sintaxis de Woodpecker permite restringir un paso a una rama o evento concreto:

steps:
  - name: deploy
    image: alpine
    when:
      branch: main
      event: push
    commands:
      - ./deploy.sh

Para profundizar en la configuración de pipelines, la guía Woodpecker CI y Forgejo: pipeline CI/CD en VPS detalla los pasos avanzados.