Woodpecker CI/CD: A Self-Hosted Engine That Keeps the Pipeline in Your Repo

What Woodpecker Solves and Who It Is For

Woodpecker addresses the problem of running continuous integration and delivery without depending on a hosted, closed-source platform. It is a self-hosted CI/CD engine written in Go, designed to be simple yet extensible. The target user is a development team that already hosts its code on a Git server such as Codeberg, Gitea, or GitHub, and wants to keep pipeline execution on its own infrastructure. Woodpecker is particularly relevant for privacy-focused projects, as evidenced by its use as the main CI/CD engine at Codeberg, an alternative Git hosting platform. The README describes it as a 'simple, yet powerful CI/CD engine with great extensibility,' which signals a focus on minimal configuration and the ability to add functionality through plugins.

The Mechanism: Pipelines as YAML in Your Repository

Woodpecker works by reading pipeline definitions from a YAML file stored in the root of your repository. This is a common pattern in modern CI/CD, but Woodpecker's approach is distinct because it does not require a separate configuration file in a web UI. The documentation (linked from the README) explains that pipelines are defined in a file such as `.woodpecker.yml`, and the engine executes the steps on a connected agent. The server component orchestrates the builds, while the agent runs the actual jobs. Communication between server and agent is not detailed in the provided material, but the architecture is typical of a distributed CI system: the server schedules jobs, and agents pick them up and report results. The default database is SQLite, which keeps setup simple for small installations, but it also means you may need to migrate to a more robust database if your workload grows.

Getting It Running: Installation and Resource Footprint

Installation is straightforward. The README points to the official installation instructions at `https://woodpecker-ci.org/docs/administration/general`. Woodpecker can be installed in various ways, including via Docker images, which are available on Docker Hub as `woodpeckerci/woodpecker-server` and presumably `woodpeckerci/woodpecker-agent`. The server runs with SQLite as the default database, so you can start with a single binary or container without configuring a separate database server. The resource requirements are modest: the server needs around 100 MB of RAM at idle, and the agent needs about 30 MB. This makes Woodpecker suitable for running on a small VPS or a Raspberry Pi, which is a key selling point for self-hosters. You will need to configure a secret for agent-server communication, but the exact steps are in the documentation, not in the README.

Extensibility Through Plugins and the Plugin Ecosystem

Woodpecker's extensibility is a core feature. The README states that 'Woodpecker can be extended via plugins' and points to a plugin overview website at `https://woodpecker-ci.org/plugins`. This site combines plugins from the core team and community maintainers, giving you a catalog of pre-built steps for common tasks like deploying to cloud providers, sending notifications, or building artifacts. The plugin model is similar to other CI systems: each plugin is a container image that runs a specific action. The advantage is that you do not have to write shell scripts for every task; you can reference a plugin in your pipeline YAML. However, the quality and maintenance of community plugins can vary, so you should verify that the plugins you rely on are actively maintained. The documentation does not specify a plugin API versioning policy, which could be a concern if you depend on third-party plugins.

A Genuine Limitation: Default SQLite and Single-Server Setup

The default use of SQLite is a double-edged sword. On one hand, it simplifies initial setup because you do not need to install and manage a separate database. On the other hand, SQLite is not designed for high-concurrency write loads, which can become a bottleneck if you have many concurrent pipelines or a large number of repositories. The README does not mention any built-in support for horizontal scaling of the server component, so you are likely limited to a single server instance. If your CI needs grow, you may need to migrate to a different database, but that migration path is not described in the provided material. Additionally, the resource footprint is for idle mode; under heavy load, RAM and CPU usage will increase, and you will need to plan for that. This makes Woodpecker a poor fit for large organizations with thousands of builds per day unless you are willing to invest in infrastructure planning.

Alternative: Compare with GitHub Actions or Drone

A direct alternative is Drone, a CI/CD engine that also runs pipelines in containers and uses a YAML configuration. Drone and Woodpecker share a common heritage; Woodpecker is a fork of Drone. The key difference is that Drone has shifted its focus to a cloud-native approach with a stronger emphasis on Kubernetes integration, while Woodpecker remains simpler and more self-contained, with SQLite as the default database. GitHub Actions is another alternative, but it is tightly coupled to GitHub and offers a hosted service, whereas Woodpecker is self-hosted and Git-agnostic. If you are already on GitHub and do not need self-hosting, GitHub Actions might be more convenient. But if you want to avoid vendor lock-in and run your CI on your own hardware, Woodpecker's lighter footprint and simpler deployment give it an edge. The choice hinges on whether you need Kubernetes-native features (Drone) or simplicity and self-hosting (Woodpecker).

Maintenance and Upgrade Cost

Woodpecker is actively maintained, with recent releases v3.18.0, v3.17.0, and v3.16.0, and the last push to the main branch was on 2026-08-24. This indicates a steady release cadence, which is good for bug fixes and security patches. However, upgrading a self-hosted CI/CD system involves downtime and testing. The documentation likely covers migration steps between major versions, but the README does not. The Apache-2.0 license for the core is permissive, allowing you to modify and redistribute the software, but you must retain the license headers. The documentation is under a different license: Creative Commons Attribution-ShareAlike 4.0 International, which means if you copy or adapt the docs, you must share your derivative works under the same license. This is a subtle but important distinction for teams that want to create internal documentation based on Woodpecker's official docs.

Editorial conclusion

Adopt Woodpecker if you run a self-hosted Git forge like Codeberg or Gitea and want a CI/CD engine that is easy to deploy, uses SQLite by default, and consumes about 100 MB RAM on the server and 30 MB on the agent at idle. Do not adopt it if you need a managed service or require a built-in pipeline editor with visual debugging. Before committing, verify that your existing plugins cover your needs and that you are comfortable with the Apache-2.0 license for the core, while noting that the documentation is CC BY-SA 4.0, which may affect how you reuse it.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes