Woodpecker CI
Lightweight self-hosted CI/CD engine that runs pipelines in Docker containers. Built for Gitea and Forgejo but works with GitHub, GitLab, and Bitbucket. Low resource footprint, YAML pipeline definitions
Quick Start
docker run -d -v woodpecker:/var/lib/woodpecker -e WOODPECKER_OPEN=true -e WOODPECKER_HOST=http://localhost -e WOODPECKER_GITEA=true -e WOODPECKER_GITEA_URL=http://your-gitea -p 8000:8000 woodpeckerci/woodpecker-server:latest Overview
Woodpecker CI is a community fork of Drone CI that provides a lightweight, self-hosted continuous integration and delivery engine. Pipelines are defined in YAML and each step runs inside its own Docker container, keeping builds clean, reproducible, and isolated from the host system. It was built with Gitea and Forgejo in mind, and the three tools form a natural self-hosted stack: code hosting, issue tracking, and CI/CD all running on your own hardware.
The pipeline definition syntax is close to both Drone CI and GitHub Actions, which makes migration from either relatively straightforward. Steps specify a Docker image to run in and commands to execute. Secrets, environment variables, and service containers (for databases or caches that a test suite needs) are all supported. The workflow covers the standard CI/CD cases: test on push, build Docker images, deploy on merge to main.
The resource footprint is genuinely small. The Woodpecker server is an orchestration layer that handles webhooks from Git, manages pipeline state, and coordinates agents. The agents do the actual build work. Both components run comfortably alongside Gitea on a 2-core VPS with 2GB RAM, which makes it practical for indie developers and small teams who want the full CI/CD stack without a dedicated build server.
The trade-offs are at the edges. The plugin ecosystem is smaller than Jenkins or GitHub Actions — there are plugins for common operations (Docker build, SSH deploy, Slack notify) but specialised integrations sometimes require writing a custom pipeline step. Matrix builds and complex conditional logic are functional but less ergonomic than in GitHub Actions.
For teams running Gitea or Forgejo who want their CI alongside their code rather than routing through GitHub Actions infrastructure, Woodpecker is the natural complement.
Woodpecker CI: Pros & Cons
| Pros (The Wins) | Cons (The Friction) |
|---|---|
| Container-native: Each step runs in its own Docker container by default. | Smaller ecosystem: Fewer plugins than Jenkins or GitHub Actions. |
| Gitea/Forgejo native: Designed to pair with self-hosted Git hosting. | Thinner community: Fewer examples and support resources than major CI tools. |
| Low resource use: Runs alongside Gitea on a small VPS comfortably. | Basic secrets UI: Advanced secrets management needs an external tool. |
| Familiar YAML syntax: Close to Drone CI and GitHub Actions; easy migration. | Matrix builds limited: Complex conditionals less polished than GitHub Actions. |
Use Cases
Specific ways to use Woodpecker CI for your workflow.
Deployment Strategy
Recommended ways to host Woodpecker CI in your own environment.