Woodpecker CI: a self-hosted CI/CD engine you can run on SQLite

The problem Woodpecker solves, and for whom

Hosted CI is convenient until your code lives somewhere the hosted CI does not reach, or until you want the build to run on machines you control. Woodpecker is a CI/CD engine you install yourself. The README describes it as "a simple, yet powerful CI/CD engine with great extensibility", and the installation section points at the project's own administration docs rather than a SaaS signup. The audience is therefore narrow and specific: teams running their own forge, or teams that want pipeline execution inside their own network. The README names one production user, Codeberg, which it describes as an alternative Git hosting platform focused on privacy and free software development and as running Woodpecker as its main CI/CD engine. That is a useful signal about the scale it can carry, but it is one data point, not a capacity guarantee. If your team already pays for a hosted CI and is happy with it, Woodpecker asks you to take on a server, an agent, a database and upgrades in exchange for control.

Server, agent, and a SQLite database by default

The architecture visible in the repository is a two-part deployment. The top level contains server/, agent/, cli/, rpc/, pipeline/, shared/, web/, and a separate Go client module in woodpecker-go/. The server holds state and talks to your forge; the agent executes pipelines. They communicate over an internal RPC layer, which is why the repository has an rpc/ package rather than a public protocol definition. The README states that Woodpecker runs with SQLite as the database by default, and go.mod also lists drivers for MySQL and PostgreSQL, so the default is a starting point rather than the only option. Resource expectations are given in the README: around 100 MB of RAM for the server and 30 MB for an agent in idle mode. That is idle, not under load, and the README does not publish figures for concurrent pipelines. Extensibility runs through plugins; the README points to a plugin overview site that combines core-team and community-maintained plugins. The go.mod file shows HashiCorp's go-plugin library, which is the usual way Go programs load plugins as separate processes, though the README does not spell out the plugin protocol.

Installing Woodpecker and running a first pipeline

The README does not print install commands. It says Woodpecker "can be installed in various ways" and links to the installation instructions at woodpecker-ci.org/docs/administration/general, so the authoritative steps live in those docs. What the repository does give you is a docker-compose.example.yaml at the top level, which is the fastest way to see a server and agent together. The README also links the server image on Docker Hub as woodpeckerci/woodpecker-server, so the container name in a compose file is traceable to the project rather than invented here. Start from the example file and read it before changing anything, because it encodes the environment variables the server needs to reach your forge.

git clone https://github.com/woodpecker-ci/woodpecker.git
cd woodpecker
cat docker-compose.example.yaml

The repository also ships a Makefile, which is how the maintainers build the binaries. The variables at the top of it are explicit about what a build needs: Go, and CGO_ENABLED set to 1, which the Makefile comments say is "only used to compile the server". That comment is a good hint about why the server and agent are not identical build targets.

make build

Build targets and their exact names are defined in the Makefile; the file is the source of truth, and the README does not list them. Once a server and agent are running, pipelines are described in YAML files. The repository keeps its own pipeline definitions in a .woodpecker/ directory at the top level, so opening that directory shows real, working configuration written by the maintainers rather than a tutorial example. The README does not document the pipeline syntax itself; it defers to the documentation site.

Where Woodpecker is the wrong choice

The strongest limitation is operational, not technical. You run the server and the agents. There is no managed offering described in the README, and the support section asks for backers on Open Collective or GitHub Sponsors rather than selling a hosted tier. If nobody on your team wants to own a database, a web service and a set of build agents, Woodpecker is the wrong tool regardless of how well it fits your forge. The second limitation is the default database. SQLite is convenient for a single server, and the README presents it as the default without qualification, but the repository does not publish guidance on when to move to MySQL or PostgreSQL. A team planning hundreds of concurrent pipelines should treat that silence as a question to answer before adopting, not after. Third, the README is thin on the things operators need most: it does not document backup, rollback or the upgrade sequence between releases, even though releases are frequent. The CHANGELOG.md at the top level is where release notes live, and it is the file to read before any version bump. Finally, the README's resource numbers are idle figures. Nothing in the README tells you what a busy agent consumes while a pipeline is running.

How Woodpecker differs from GitHub Actions and Drone

The comparison that matters is with GitHub Actions, because it is the default for many teams and it is managed. Actions runs on GitHub's infrastructure and is tied to GitHub as the forge. Woodpecker inverts both: you supply the machines, and the forge is a configuration choice, with SDK dependencies in go.mod for GitHub, Gitea, Forgejo and Bitbucket. If your repositories already live on GitHub and you have no reason to leave, Actions removes an entire class of operational work that Woodpecker hands back to you. Woodpecker earns its place when the repositories do not live on GitHub, or when the build must run inside your own network. The second comparison is with Drone, the project Woodpecker's pipeline model descends from. Both are self-hosted and plugin-oriented, and Woodpecker's Apache-2.0 licence is a meaningful difference from Drone's licensing history for teams that care about that. The concrete distinction in this repository is the default database: Woodpecker states that it runs with SQLite by default, which lowers the entry cost to a single container plus an agent, while a Drone deployment is conventionally described around an external database. That is a difference in the first hour of setup, not in the long run.

Maintenance cadence, upgrades, and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-08-24. Releases are frequent: v3.16.0 on 2026-06-27, v3.17.0 on 2026-07-31, and v3.18.0 on 2026-08-24. A roughly monthly minor release cadence means upgrade cost is a recurring line item, not a one-off. Because a deployment has a server and at least one agent, an upgrade touches both, and the repository does not document a rollback procedure, so the practical approach is to pin image tags and read CHANGELOG.md before moving. The Go module path is versioned, go.woodpecker-ci.org/woodpecker/v3, which tells you the API surface is expected to change across major versions rather than within them. On licensing, the README states Woodpecker is Apache 2.0 licensed and that source files carry a header indicating the applicable licence and copyright. It also states that everything in docs/ is under Creative Commons Attribution-ShareAlike 4.0 International, which is a different licence from the code. If you plan to redistribute the documentation or embed it in a product, that split matters, and it is worth having someone who can read licences confirm what your use requires.

Editorial conclusion

Adopt Woodpecker if you self-host your forge or want CI next to your own infrastructure and can accept SQLite as the default database. Do not adopt it if you need a managed service or a hosted runner fleet, because the project ships a server and an agent you operate yourself. Before committing, verify which forge you will connect, whether the SQLite default holds up for your pipeline volume, and how you will upgrade the server and every agent in step, since the repository does not document a rollback path.

Frequently asked questions

Official sources

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