Woodpecker CI – A No-Nonsense CI/CD Tool for Self-Hosted Git Workflows
What is Woodpecker CI
Woodpecker CI is one of those tools that doesn’t try to be everything — and that’s a good thing. It’s a simple, clean continuous integration system you can run on your own infrastructure. No SaaS layers, no vendor lock-in, no massive overhead. You connect it to your Git server — Gitea, GitHub, GitLab, whatever fits — and it runs your build pipelines inside Docker containers. That’s it.
Originally forked from Drone CI, it’s now a community-driven project with a clear focus: fast, portable builds triggered by Git events. Pipelines are written in YAML and executed using container steps. Everything is isolated, traceable, and easy to reproduce.
It’s ideal for small teams, internal infrastructure, or anyone who wants to keep CI/CD simple and under control — especially in places where running Jenkins is overkill and using cloud services isn’t an option.
Technical Summary
| Attribute | Detail |
| Supported Platforms | Linux (natively), macOS and Windows (via containers) |
| Pipeline Execution | Docker containers, one per step |
| Git Integration | Gitea, GitHub, GitLab, Bitbucket, Codeberg |
| Pipeline Format | YAML (.woodpecker.yml) |
| Authentication | OAuth2, tokens, or basic auth |
| Licensing | Apache 2.0 |
| Typical Deployment | Docker, bare-metal, or Kubernetes |
| Current Version | 2.5.0 (as of July 2025) |
| Website | https://woodpecker-ci.org |
| Containers | woodpeckerci/woodpecker-server, woodpeckerci/woodpecker-agent |
How It Works
The design is split into two main services: the server and one or more agents.
– The server handles repository connections, webhooks, UI, and pipeline scheduling.
– Agents do the actual work — each pipeline step runs in a Docker container on the agent side.
When someone pushes to a connected repo, the server catches the webhook, reads the pipeline config (.woodpecker.yml), and assigns the job to an available agent. The agent pulls down the code, runs the steps in clean containers, and sends logs and results back to the UI.
There’s no extra orchestration layer, no central database magic, and no special runner binaries. Just clean, reproducible builds in containers.
Quick Setup (Docker)
Here’s a minimal working setup using Docker.
Create a network:
docker network create woodpecker
Start the server:
docker run -d –name woodpecker-server
–network woodpecker
-e WOODPECKER_GITEA=true
-e WOODPECKER_GITEA_URL=https://git.example.com
-e WOODPECKER_GITEA_CLIENT=your-client-id
-e WOODPECKER_GITEA_SECRET=your-secret
-e WOODPECKER_SECRET=shared-secret
-p 8000:8000
woodpeckerci/woodpecker-server
Start the agent:
docker run -d –name woodpecker-agent
–network woodpecker
-e WOODPECKER_SERVER=woodpecker-server:9000
-e WOODPECKER_SECRET=shared-secret
-v /var/run/docker.sock:/var/run/docker.sock
woodpeckerci/woodpecker-agent
Open http://localhost:8000 and link your repo — you’re ready to go.
Example Pipeline File
pipeline:
build:
image: node:20
commands:
– npm install
– npm run test
docker-push:
image: plugins/docker
settings:
repo: my-registry.local/app
tags: latest
Real-World Usage
– Developers running CI in secure, internal environments
– Self-hosted Gitea + Woodpecker setups for in-house projects
– Lightweight CI/CD for microservices — no Jenkins, no Kubernetes required
– Fast pipelines for container builds, tests, and deployments
– Infrastructure teams needing CI/CD without a cloud dependency
