Woodpecker CI — Simple Yet Powerful CI/CD Engine

What it is

Woodpecker CI is a lightweight, container-based CI/CD engine forked from Drone. Every pipeline step runs in an isolated Docker container, defined in a simple YAML file. It integrates with GitHub, GitLab, Gitea, Forgejo, and Bitbucket.

Woodpecker targets small to mid-size teams and self-hosters who want CI/CD without the complexity of Jenkins or the cost of GitHub Actions minutes.

How it saves time or tokens

Woodpecker pipelines are minimal YAML. A typical build-test-deploy pipeline is 20 lines. There is no plugin marketplace to navigate because any Docker image is a valid pipeline step. Need node:20? Use it directly. Need postgres:16 as a service? Add it as a service block.

Self-hosting Woodpecker on a $5/month VPS gives you unlimited build minutes, compared to GitHub Actions' 2,000 free minutes per month.

How to use

1. Deploy Woodpecker server: docker compose up -d with the official compose file
2. Register your Git forge (GitHub, GitLab, Gitea) as an OAuth app
3. Activate your repository in the Woodpecker UI
4. Add a .woodpecker.yml file to your repository root

Example

# .woodpecker.yml
steps:
  - name: build
    image: node:20-alpine
    commands:
      - npm ci
      - npm run build

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

  - name: deploy
    image: alpine/curl
    commands:
      - curl -X POST https://deploy.example.com/webhook
    when:
      branch: main
      event: push

services:
  - name: database
    image: postgres:16
    environment:
      POSTGRES_DB: test
      POSTGRES_PASSWORD: test

Related on TokRepo

• DevOps tools -- CI/CD and infrastructure tools
• Automation tools -- Build automation and workflow tools

Common pitfalls

• Woodpecker uses .woodpecker.yml by default, not .drone.yml; migrating from Drone requires renaming and minor syntax adjustments
• Agent-server communication requires proper networking; in Docker setups, ensure the agent can reach the server's gRPC port
• Secret management is per-repository in the UI; there is no global secret store without a plugin or external vault