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

Escopo Definido por Visível para
Repositório Dono do repo Somente aquele repositório
Organização Admin da org Todos os repos da org
Global Admin do servidor Todos 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

Plugin Imagem Propósito
Docker woodpeckerci/plugin-docker-buildx Construir e publicar imagens Docker
S3 woodpeckerci/plugin-s3 Enviar artefatos para S3
Slack plugins/slack Notificações de build
Webhook woodpeckerci/plugin-webhook POST 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

Recurso Woodpecker Drone OSS Gitea Actions Jenkins Concourse
Licença MIT Apache 2.0 MIT MIT Apache 2.0
RAM (inativo) ~50 MB ~80 MB ~100 MB ~500 MB ~200 MB
Matrix builds Sim Não (OSS) Sim Sim Sim
Multi-pipeline Sim Não (OSS) Sim Sim Não
Backend Kubernetes Sim Sim Não Sim Nã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

Problema Solução
Agente não conecta Verifique que WOODPECKER_AGENT_SECRET coincide; confirme que a porta 9000 está aberta
Pipeline preso em pendente Nenhum agente conectado ou rótulos não coincidem; verifique status do agente na UI
Webhook não dispara Verifique que o Gitea consegue alcançar o servidor Woodpecker; revise Configurações > Hooks
Segredos não injetados O nome do segredo deve coincidir exatamente; revise o filtro de eventos do segredo
Build multiplataforma falha Verifique 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