Woodpecker CI, senza alcun SaaS di mezzo

Come installare Woodpecker CI con Docker Compose

Server e agent su un host, collegati a GitHub in questo esempio. Sostituite il blocco della forge con le variabili di Gitea, Forgejo, GitLab o Bitbucket se la vostra forge è una di quelle.

1. 1

   Installare Docker e Compose

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

   Entrambi i container e ogni passo della pipeline girano su questo demone, quindi è l'unica dipendenza di cui l'host ha bisogno.

2. 2

   Registrare un'applicazione OAuth sulla vostra forge

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

   Woodpecker autentica gli utenti attraverso la forge e legge i repository con quel permesso, quindi l'id client e il segreto che restituisce sono ciò che serve al server. Ogni forge supportata ha un modulo equivalente.

3. 3

   Generare il segreto condiviso dell'agent

   openssl rand -hex 32

   Server e agent si autenticano a vicenda con questa stringa, e la documentazione Woodpecker indica esattamente questo comando per produrla. Tenetela fuori dal file compose - mettetela in un file .env accanto.

4. 4

   Scrivere il file 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:

   Questo è l'esempio ufficiale. WOODPECKER_HOST è l'URL pubblico che raggiungono utenti e webhook, la porta 8000 è l'interfaccia web e la 9000 è la porta gRPC su cui si collegano gli agent. WOODPECKER_OPEN=true lascia entrare chiunque abbia un account sulla forge - disattivatelo appena il vostro team è registrato.

5. 5

   Avviarlo

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

   L'agent si collega al server con il segreto condiviso e si registra da solo al primo contatto. Se entra in ciclo con un errore di autenticazione, i due segreti non coincidono - quasi sempre perché il file .env non è stato letto.

6. 6

   Aggiungere una pipeline

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

   Fate il commit come .woodpecker.yaml, abilitate il repository nell'interfaccia web perché venga creato il webhook, e fate push. Ogni passo è un container, ed è per questo che all'agent serve il socket di Docker.

Verificato sulla documentazione ufficiale il 2026-08-15 - leggi la fonte