Woodpecker CI: A Clean CI/CD System That Plays By Your Rules
You know that feeling when tools get in your way more than they help? Woodpecker CI avoids that trap. It’s a self-hosted, container-native CI/CD system — designed for engineers who like their pipelines predictable, their tools minimal, and their infrastructure under their control.
Originally forked from Drone, it’s stripped of fluff and focused on the essentials. Pipelines are defined in YAML. Each step runs in a container. It connects to your Git service, runs your jobs, and stays out of the spotlight — just as it should.
You don’t need a fleet of microservices to run it. A small server will do. And if things grow? It scales with you — agents can be added on demand, and the setup still stays readable.
What Woodpecker CI Brings to the Table
| Feature | Description |
| Container-Native Pipelines | Each job step runs in a Docker container — clean, reproducible, isolated. |
| Readable Pipeline Logic | Configuration lives in `.woodpecker.yml`, tracked in version control. |
| Low Resource Overhead | Can run on small virtual machines or edge hardware without breaking a sweat. |
| Flexible Workflow Control | Supports serial jobs, parallel steps, and conditional logic. |
| Git OAuth Integration | Works with GitHub, GitLab, Gitea, Bitbucket, and others. |
| Plugin-Friendly Design | Build, test, deploy steps can use official or custom Docker-based plugins. |
| Scalable Agent System | Add agents manually or dynamically scale based on job load. |
| Database Choices | Use SQLite by default, or upgrade to PostgreSQL/MySQL for heavier use cases. |
Getting It Running
Woodpecker can be deployed in several ways depending on how you manage your environment.
1. Docker Compose (Quick Setup)
A common and easy approach for local or single-host setups:
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server
ports:
– 8000:8000
volumes:
– ./data:/var/lib/woodpecker
woodpecker-agent:
image: woodpeckerci/woodpecker-agent
environment:
WOODPECKER_SERVER: http://woodpecker-server:8000
WOODPECKER_AGENT_SECRET: your_secret
2. Running Binaries (Manual Setup)
Download the binaries for `woodpecker-server` and `woodpecker-agent`. Start the server:
./woodpecker-server &
Then launch the agent:
./woodpecker-agent –server http://localhost:8000 –secret your_secret
3. Kubernetes Deployment (for Larger Installations)
Use the Helm chart to deploy in Kubernetes. It supports:
– OAuth credentials
– volume persistence
– custom resource limits
– affinity and toleration rules
– secret management
Workflow Overview (What Using It Feels Like)
- Connect Git
Configure Git OAuth access and define user permissions.2. Create a `.woodpecker.yml`
Here’s a minimal example:
pipeline:
build:
image: alpine
commands:
– echo “Starting build”
– ./build.sh
- Start the Agents
They automatically pick up jobs and execute tasks in containers.4. Watch It Work
Logs, statuses, history — visible via the web interface or CLI. No guesswork.
When Does Woodpecker Make Sense?
– You already self-host Git and want a local CI/CD to match.
– You’re tired of tools that overcomplicate simple workflows.
– You want clear pipeline logic and full control over execution.
– You need something light but scalable — without cloud lock-in.
Final Thought
Woodpecker CI doesn’t try to be everything. It’s more like that quiet utility that does one job well — and then gets out of your way. If you’re looking for something you can actually maintain, without paying for features you’ll never use, it might be exactly what your team needs.
