TL;DR — Resumo Rápido

Implante o Woodpecker CI para CI/CD leve e auto-hospedado. Configure pipelines, segredos, agentes e integração com Gitea, GitHub e GitLab facilmente.

O Woodpecker CI é um sistema CI/CD leve e auto-hospedado, derivado do Drone CI, que executa pipelines nativos em contêineres com uso mínimo de recursos. Este guia abrange a instalação completa, integração com Gitea, sintaxe de pipelines, gerenciamento de segredos e um pipeline prático para implantação de uma aplicação Go.

Pré-requisitos

  • Servidor Linux com Docker e Docker Compose.
  • Pelo menos 512 MB de RAM para servidor + agente (1 GB recomendado).
  • Uma instância Gitea, Forgejo, GitHub ou GitLab para OAuth.
  • Portas 8000 (HTTP) e 9000 (comunicação gRPC com agentes) abertas.

Passo 1: Arquitetura do Woodpecker

O Woodpecker segue um modelo servidor + agente:

  • Servidor — Gerencia UI web, API, webhooks e agendamento de pipelines.
  • Agente — Consulta o servidor por trabalho e executa etapas dentro de contêineres Docker.
  • Forge — O provedor Git (Gitea, GitHub, GitLab) que envia webhooks e autenticação OAuth.
  • Pipeline — Definido em .woodpecker.yml na raiz do repositório.

Passo 2: Instalar com Docker Compose

Criar o App OAuth no Gitea

No Gitea: Configurações → Aplicativos → OAuth2 → Criar aplicativo OAuth2

  • Nome: Woodpecker CI
  • URL de redirecionamento: http://seu-servidor-woodpecker:8000/authorize

Copie o Client ID e o Client Secret.

Configuração com Docker Compose

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    container_name: woodpecker-server
    restart: always
    ports:
      - "8000:8000"
      - "9000:9000"
    volumes:
      - woodpecker-server-data:/var/lib/woodpecker/
    environment:
      - WOODPECKER_OPEN=false
      - WOODPECKER_HOST=http://seu-servidor:8000
      - WOODPECKER_GITEA=true
      - WOODPECKER_GITEA_URL=http://seu-gitea:3000
      - WOODPECKER_GITEA_CLIENT=seu-client-id
      - WOODPECKER_GITEA_SECRET=seu-client-secret
      - WOODPECKER_AGENT_SECRET=segredo-compartilhado-forte

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:latest
    container_name: woodpecker-agent
    restart: always
    depends_on:
      - woodpecker-server
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WOODPECKER_SERVER=woodpecker-server:9000
      - WOODPECKER_AGENT_SECRET=segredo-compartilhado-forte
      - WOODPECKER_MAX_PROCS=2

volumes:
  woodpecker-server-data:
docker compose up -d

Passo 3: Sintaxe do Pipeline (.woodpecker.yml)

Pipeline Básico

steps:
  - name: test
    image: golang:1.22
    commands:
      - go test ./...

  - name: build
    image: golang:1.22
    commands:
      - go build -o app .

  - name: notificar
    image: plugins/slack
    settings:
      webhook:
        from_secret: slack_webhook
    when:
      - status: [success, failure]

Serviços (Banco de Dados, Redis)

services:
  - name: postgres
    image: postgres:16
    environment:
      POSTGRES_DB: testdb
      POSTGRES_USER: test
      POSTGRES_PASSWORD: test

steps:
  - name: test
    image: golang:1.22
    environment:
      DATABASE_URL: "postgres://test:test@postgres/testdb?sslmode=disable"
    commands:
      - go test -tags integration ./...

Matrix Builds

matrix:
  GO_VERSION:
    - "1.21"
    - "1.22"

steps:
  - name: test
    image: "golang:${GO_VERSION}"
    commands:
      - go test ./...

Passo 4: Gerenciamento de Segredos

EscopoDefinido porVisível para
RepositórioDono do repoSomente aquele repositório
OrganizaçãoAdmin da orgTodos os repos da org
GlobalAdmin do servidorTodos os repositórios
steps:
  - name: deploy
    image: alpine
    environment:
      DEPLOY_KEY:
        from_secret: deploy_key
    commands:
      - echo "$DEPLOY_KEY" | base64 -d > /tmp/key
      - ./deploy.sh

Passo 5: Plugins

PluginImagemPropósito
Dockerwoodpeckerci/plugin-docker-buildxConstruir e publicar imagens Docker
S3woodpeckerci/plugin-s3Enviar artefatos para S3
Slackplugins/slackNotificações de build
Webhookwoodpeckerci/plugin-webhookPOST para URLs arbitrárias

Passo 6: Agentes, CLI e Builds Multiplataforma

Rótulos de Agentes

WOODPECKER_FILTER_LABELS=platform=linux/arm64,type=build
labels:
  platform: linux/arm64

steps:
  - name: build-arm
    image: golang:1.22
    commands:
      - GOARCH=arm64 go build -o app-arm64 .

woodpecker-cli

export WOODPECKER_SERVER=http://seu-servidor:8000
export WOODPECKER_TOKEN=seu-token-api

woodpecker pipeline ls dono/repo
woodpecker pipeline start dono/repo --branch main
woodpecker secret add --repository dono/repo --name deploy_key --value "$(cat key.pem)"

Tarefas Agendadas (Cron)

woodpecker cron add --repository dono/repo --name build-noturno \
  --expr "0 2 * * *" --branch main

Woodpecker vs Alternativas

RecursoWoodpeckerDrone OSSGitea ActionsJenkinsConcourse
LicençaMITApache 2.0MITMITApache 2.0
RAM (inativo)~50 MB~80 MB~100 MB~500 MB~200 MB
Matrix buildsSimNão (OSS)SimSimSim
Multi-pipelineSimNão (OSS)SimSimNão
Backend KubernetesSimSimNãoSimNão

Exemplo Prático: Pipeline para Aplicação Go

steps:
  - name: test
    image: golang:1.22
    commands:
      - go vet ./...
      - go test -race ./...

  - name: build-docker
    image: woodpeckerci/plugin-docker-buildx
    settings:
      repo: registry.exemplo.com/minhaapp
      tags: ["latest", "${CI_COMMIT_SHA:0:8}"]
      platforms: "linux/amd64,linux/arm64"
      username:
        from_secret: registry_user
      password:
        from_secret: registry_password
    when:
      - branch: main
        event: push

  - name: deploy
    image: alpine
    environment:
      DEPLOY_KEY:
        from_secret: deploy_ssh_key
      DEPLOY_HOST:
        from_secret: deploy_host
    commands:
      - apk add --no-cache openssh-client
      - echo "$DEPLOY_KEY" | base64 -d > /tmp/key && chmod 600 /tmp/key
      - ssh -i /tmp/key -o StrictHostKeyChecking=no deploy@$DEPLOY_HOST
          "docker pull registry.exemplo.com/minhaapp:latest && docker restart minhaapp"
    when:
      - branch: main
        event: push

Problemas Comuns

ProblemaSolução
Agente não conectaVerifique que WOODPECKER_AGENT_SECRET coincide; confirme que a porta 9000 está aberta
Pipeline preso em pendenteNenhum agente conectado ou rótulos não coincidem; verifique status do agente na UI
Webhook não disparaVerifique que o Gitea consegue alcançar o servidor Woodpecker; revise Configurações > Hooks
Segredos não injetadosO nome do segredo deve coincidir exatamente; revise o filtro de eventos do segredo
Build multiplataforma falhaVerifique se QEMU está instalado ou use privileged: true

Resumo

  • O Woodpecker CI é um fork leve do Drone CI usando ~50 MB de RAM com arquitetura servidor + agente.
  • Integra com 6 forges (Gitea, Forgejo, GitHub, GitLab, Bitbucket) via OAuth2.
  • Os pipelines usam .woodpecker.yml com etapas, serviços, matrix builds e multi-pipeline por caminhos.
  • Os segredos são escopados por repositório, organização ou globalmente, com backends externos como Vault.
  • O woodpecker-cli permite gerenciar pipelines, segredos e tarefas cron pelo terminal.

Artigos Relacionados