O Woodpecker é um motor de CI/CD leve e extensível que foi projetado para funcionar nativamente com containers. Ao utilizar Docker como base para seus pipelines, ele garente isolamento reprodutível, onde o ambiente de execução no servidor de integração é idêntico ao ambiente de produção. A arquitetura é composta principalmetne por dois componentes: o Server, que gerencia a interface web, autenticação e armazenamento de metadados, e o Agent, que executa as tarefas de build através de containers Docker.

Implantação via Docker Compose

A forma mais rápida de iniciar o Woodpecker é utilizando o Docker Compose. Abaixo, configuramos tanto o servidor quanto o agente em uma única rede, permitindo a comunicação entre eles e o controle sobre o socket do Docker.

version: '3.8'

services:
  woodpecker_server:
    image: woodpeckerci/woodpecker-server:latest
    ports:
      - "8000:8000"
      - "9000:9000"
    volumes:
      - woodpecker_data:/var/lib/woodpecker
    environment:
      - WOODPECKER_OPEN=true
      - WOODPECKER_ADMIN=seu_usuario_admin

  woodpecker_agent:
    image: woodpeckerci/woodpecker-agent:latest
    command: agent
    restart: always
    depends_on:
      - woodpecker_server
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WOODPECKER_SERVER=woodpecker_server:9000

volumes:
  woodpecker_data:

Definição de Pipelines com YAML

Os pipelines são definidos no arquivo .woodpecker.yml na raiz do repositório. A sintaxe permite definir múltiplos passos, cada um rodando em um container específico. Neste exemplo, configuramos um fluxo de trablaho para uma aplicação Go, alterando a estrutura para separar claramente a compilação dos testes.

steps:
  build_stage:
    image: golang:1.22-alpine
    commands:
      - go mod download
      - go build -ldflags="-s -w" -o bin/app ./cmd/server

  test_stage:
    image: golang:1.22-alpine
    commands:
      - go test -v -race ./...

  publish_stage:
    image: plugins/docker
    settings:
      repo: organizacao/projeto
      tags: latest
      username:
        from_secret: REGISTRY_USER
      password:
        from_secret: REGISTRY_PASSWORD

Execução Paralela e Agrupamento

Para otimizar o tempo de execução, o Woodpecker permite rodar etapas em paralelo utilizando grupos. No exemplo abaixo, testes unitários e de integração rodam simultaneamente após o checkout do código.

steps:
  lint_check:
    image: node:20
    group: validation
    commands:
      - npm install
      - npm run lint

  unit_tests:
    image: node:20
    group: validation
    commands:
      - npm run test:unit

  integration_tests:
    image: node:20
    group: validation
    commands:
      - npm run test:integration

Gerenciamento de Segredos

Credenciais e tokens sensíveis nunca devem ser escritos diretamente no arquivo de configuração. O Woodpecker oferece um sistema de segredos injetados no ambiente de execução. Eles podem ser configurados via interface gráfica ou CLI e referenciados no pipeline.

steps:
  deploy:
    image: plugins/ssh
    settings:
      host: servidor.producao.com
      user: deploy_user
      key:
        from_secret: SSH_PRIVATE_KEY
      script:
        - docker pull minha-imagem:latest
        - docker-compose up -d

Otimização com Cache de Docker

Acelerar o processo de build é essencial para manter a agilidade do time. Utilizar o mecanismo de cache do Docker ao construir imagens reduz significativamente o tempo de transferência de camadas redundantes.

steps:
  build_image:
    image: docker:dind
    commands:
      - docker login -u $USER -p $PASS registry.exemplo.com
      - |
        docker build \
          --cache-from registry.exemplo.com/webapp:cache \
          -t registry.exemplo.com/webapp:$CI_COMMIT_SHA .
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Depuração Local de Pipelines

O Woodpecker CLI permite executar pipelines localmente antes de enviar as alterações para o repositório. Isso é útil para validar mudanças na configuração sem consumir recursos do servidor CI.

# Executa o pipeline definido no diretório atual
woodpecker-cli exec

# Executa um arquivo específico
woodpecker-cli exec --pipeline-file ./cicd/build.yml

Estratégias de Deploy em Múltiplos Ambientes

A ferramenta suporta diferentes estratégias de deploy baseadas em branches ou eventos. É possível configurar deploys manuais para produção e automáticos para ambientes de desenvolvimento, utilizando condições de execução.

steps:
  deploy_production:
    image: plugins/kubectl
    settings:
      server: https://k8s.api.prod
    when:
      event: deployment
      target: production

  deploy_staging:
    image: plugins/kubectl
    settings:
      server: https://k8s.api.staging
    when:
      branch: main
      event: push