Woodpecker CI, sin ningún SaaS por medio

Cómo instalar Woodpecker CI con Docker Compose

Servidor y agente en un host, conectados a GitHub en este ejemplo. Cambie el bloque de la forja por las variables de Gitea, Forgejo, GitLab o Bitbucket si su forja es una de esas.

1. 1

   Instalar Docker y Compose

   sudo apt install docker.io docker-compose-v2
   sudo systemctl enable --now docker

   Los dos contenedores y cada paso de la pipeline se ejecutan sobre este demonio, así que es la única dependencia que necesita el host.

2. 2

   Registrar una aplicación OAuth en su forja

   # GitHub: Settings -> Developer settings -> OAuth Apps -> New OAuth App
   # Homepage URL:     https://ci.example.com
   # Authorization callback: https://ci.example.com/authorize

   Woodpecker autentica a los usuarios a través de la forja y lee repositorios con ese permiso, así que el id de cliente y el secreto que devuelve son lo que necesita el servidor. Cada forja soportada tiene un formulario equivalente.

3. 3

   Generar el secreto compartido del agente

   openssl rand -hex 32

   El servidor y los agentes se autentican entre sí con esta cadena, y la documentación de Woodpecker nombra exactamente este comando para producirla. Manténgala fuera del fichero de compose - póngala en un fichero .env al lado.

4. 4

   Escribir el fichero de compose

   services:
     woodpecker-server:
       image: woodpeckerci/woodpecker-server:v3
       ports:
         - 8000:8000
       volumes:
         - woodpecker-server-data:/var/lib/woodpecker/
       environment:
         - WOODPECKER_OPEN=true
         - WOODPECKER_HOST=${WOODPECKER_HOST}
         - WOODPECKER_GITHUB=true
         - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
         - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
         - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
     woodpecker-agent:
       image: woodpeckerci/woodpecker-agent:v3
       command: agent
       restart: always
       depends_on:
         - woodpecker-server
       volumes:
         - woodpecker-agent-config:/etc/woodpecker
         - /var/run/docker.sock:/var/run/docker.sock
       environment:
         - WOODPECKER_SERVER=woodpecker-server:9000
         - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
   volumes:
     woodpecker-server-data:
     woodpecker-agent-config:

   Este es el ejemplo oficial. WOODPECKER_HOST es la URL pública a la que llegan usuarios y webhooks, el puerto 8000 es la interfaz web y el 9000 es el puerto gRPC por el que se conectan los agentes. WOODPECKER_OPEN=true deja entrar a cualquiera con una cuenta en la forja - desactívelo en cuanto su equipo esté registrado.

5. 5

   Arrancarlo

   docker compose up -d
   docker compose logs -f woodpecker-agent

   El agente se conecta al servidor con el secreto compartido y se registra solo en el primer contacto. Si entra en bucle con un error de autenticación, los dos secretos no coinciden - casi siempre porque no se leyó el fichero .env.

6. 6

   Añadir una pipeline

   when:
     - event: push
   
   steps:
     - name: smoke
       image: alpine:latest
       commands:
         - cat /etc/os-release
         - echo "built on $CI_MACHINE"

   Haga commit de eso como .woodpecker.yaml, active el repositorio en la interfaz web para que se cree el webhook, y suba los cambios. Cada paso es un contenedor, y por eso el agente necesita el socket de Docker.

Comprobado con la documentación oficial el 2026-08-15 — leer la fuente