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

FAQ

Q: What's the relationship between Woodpecker and Drone? A: Woodpecker is a community fork of Drone CI, created after Drone moved in a more commercial direction. Woodpecker stays 100% open source and community-governed, and continues to add new features (multi-pipeline, Cron, UI improvements).

Q: Does it work well with Gitea? A: It's a great fit. Woodpecker + Gitea is the most popular self-hosted Git + CI/CD combo — simple to configure, low resource consumption, and a perfect self-hosted alternative to GitHub + Actions.

Q: Does it support Kubernetes executors? A: Yes. In addition to the Docker agent, Woodpecker offers a Kubernetes backend that runs pipeline steps as K8s Pods.

Sources & Credits

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