Woodpecker CI, sem qualquer SaaS pelo meio

Como instalar o Woodpecker CI com Docker Compose

Servidor e agente num host, ligados ao GitHub neste exemplo. Troque o bloco da forja pelas variáveis do Gitea, Forgejo, GitLab ou Bitbucket se a sua forja for uma dessas.

1. 1

   Instalar o Docker e o Compose

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

   Ambos os contentores e cada passo da pipeline correm neste daemon, portanto é a única dependência de que o host precisa.

2. 2

   Registar uma aplicação OAuth na sua forja

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

   O Woodpecker autentica os utilizadores através da forja e lê repositórios com essa autorização, portanto o id de cliente e o segredo que ela devolve são o que o servidor precisa. Cada forja suportada tem um formulário equivalente.

3. 3

   Gerar o segredo partilhado do agente

   openssl rand -hex 32

   O servidor e os agentes autenticam-se um ao outro com esta cadeia, e a documentação do Woodpecker nomeia exatamente este comando para a produzir. Mantenha-a fora do ficheiro compose - ponha-a num ficheiro .env ao lado.

4. 4

   Escrever o ficheiro 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 é o exemplo oficial. WOODPECKER_HOST é o URL público a que chegam utilizadores e webhooks, a porta 8000 é a interface web e a 9000 é a porta gRPC onde os agentes se ligam. WOODPECKER_OPEN=true deixa entrar qualquer pessoa com conta na forja - desligue-o assim que a sua equipa estiver registada.

5. 5

   Arrancar

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

   O agente liga-se ao servidor com o segredo partilhado e regista-se sozinho no primeiro contacto. Se entrar em ciclo com um erro de autenticação, os dois segredos não coincidem - quase sempre porque o ficheiro .env não foi lido.

6. 6

   Acrescentar uma pipeline

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

   Faça commit disso como .woodpecker.yaml, ative o repositório na interface web para que o webhook seja criado, e faça push. Cada passo é um contentor, e é por isso que o agente precisa do socket do Docker.

Verificado na documentação oficial em 2026-08-15 — ler a fonte