Woodpecker CI — Simple Yet Powerful CI/CD Engine

What Woodpecker Does

• Container-Native: Every pipeline step runs in its own Docker container
• YAML Pipelines: Simple, readable pipeline definitions in .woodpecker.yml
• Multi-Platform: Build for linux/amd64, arm64, arm, and windows
• Git Integration: GitHub, GitLab, Gitea, Forgejo, and Bitbucket support
• Parallel Execution: Run steps and pipelines in parallel
• Matrix Builds: Test across multiple versions/configurations
• Secrets Management: Encrypted secrets per repository or organization
• Plugins: 100+ community plugins for Docker, Slack, S3, etc.
• Cron Jobs: Schedule periodic pipeline runs

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Git Forge   │────▶│  Woodpecker  │────▶│  Woodpecker  │
│  (GitHub/    │webhook│  Server     │     │  Agent(s)    │
│  Gitea/etc)  │     │  (Go)        │     │  (Docker)    │
└──────────────┘     └──────────────┘     └──────────────┘

• Server: Handles webhooks, manages pipelines, serves web UI
• Agent: Executes pipeline steps in Docker containers (can run on multiple machines)

Self-Hosting

Docker Compose

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    ports:
      - "8000:8000"
    environment:
      WOODPECKER_OPEN: "true"
      WOODPECKER_HOST: https://ci.yourdomain.com
      WOODPECKER_GITHUB: "true"
      WOODPECKER_GITHUB_CLIENT: your-github-oauth-client-id
      WOODPECKER_GITHUB_SECRET: your-github-oauth-client-secret
      WOODPECKER_AGENT_SECRET: your-shared-agent-secret
    volumes:
      - woodpecker-data:/var/lib/woodpecker

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:latest
    environment:
      WOODPECKER_SERVER: woodpecker-server:9000
      WOODPECKER_AGENT_SECRET: your-shared-agent-secret
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

volumes:
  woodpecker-data:

With Gitea

environment:
  WOODPECKER_GITEA: "true"
  WOODPECKER_GITEA_URL: https://gitea.yourdomain.com
  WOODPECKER_GITEA_CLIENT: your-gitea-oauth-client-id
  WOODPECKER_GITEA_SECRET: your-gitea-oauth-client-secret

Pipeline Examples

Basic CI

# .woodpecker.yml
steps:
  - name: install
    image: node:20
    commands:
      - npm ci

  - name: lint
    image: node:20
    commands:
      - npm run lint

  - name: test
    image: node:20
    commands:
      - npm test

  - name: build
    image: node:20
    commands:
      - npm run build

With Services (Database Testing)

steps:
  - name: test
    image: python:3.12
    commands:
      - pip install -r requirements.txt
      - pytest --db-url=postgresql://test:test@postgres:5432/testdb

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

Docker Build & Push

steps:
  - name: build-and-push
    image: woodpeckerci/plugin-docker-buildx
    settings:
      repo: myregistry.com/myapp
      tags: latest,${CI_COMMIT_SHA:0:8}
      username:
        from_secret: docker_username
      password:
        from_secret: docker_password
    when:
      branch: main
      event: push

Matrix Builds

matrix:
  GO_VERSION:
    - "1.21"
    - "1.22"
  DATABASE:
    - postgres
    - mysql

steps:
  - name: test
    image: golang:${GO_VERSION}
    commands:
      - go test ./... -db=${DATABASE}

Multi-Pipeline (Parallel)

# .woodpecker/test.yml
steps:
  - name: test
    image: node:20
    commands:
      - npm test

# .woodpecker/deploy.yml
depends_on:
  - test
steps:
  - name: deploy
    image: alpine
    commands:
      - ./deploy.sh
    when:
      branch: main

Woodpecker vs Alternatives

常见问题

Q: Woodpecker 和 Drone 有什么关系？ A: Woodpecker 是 Drone CI 的社区 fork，创建于 Drone 转向更商业化的方向之后。Woodpecker 保持了 100% 开源、社区治理，并持续添加新功能（如多管道、Cron、改进的 UI）。

Q: 可以和 Gitea 配合使用吗？ A: 非常适合。Woodpecker + Gitea 是最流行的自托管 Git + CI/CD 组合。配置简单，资源消耗低，是 GitHub + Actions 的完美自托管替代。

Q: 支持 Kubernetes 执行器吗？ A: 支持。除了 Docker agent，Woodpecker 还提供 Kubernetes backend，将 pipeline 步骤作为 K8s Pod 运行。

来源与致谢

• GitHub: woodpecker-ci/woodpecker — 6.8K+ ⭐ | Apache-2.0
• 官网: woodpecker-ci.org