Woodpecker CI: a Drone fork that runs on SQLite by default

The flagship deployment is Codeberg

There is one production reference in the README, and it is a substantial one.

Woodpecker is used as the main CI/CD engine at Codeberg, an alternative Git hosting platform with a focus on privacy and free software development.

That is worth more than a benchmark claim, because it is a named, operating, multi-user instance rather than a measurement. It also tells you what kind of deployment suits the tool: somewhere with a large number of small open-source projects and contributors who need their own pipelines without an administrator per repository.

The rest of the README's community infrastructure points the same way. There is a self-hosted translation instance for Weblate with its own per-language status page, a Matrix space, a pre-commit results page, and a Core Infrastructure best practices badge. That is a project that has built out its own hosting rather than relying on a single external service.

The consequence is that the reference installation is visible if you want one, and the badge set tells you the project holds itself to an external standard rather than only to its own tooling.

SQLite by default, and CGO only on the server

The installation section contains the only quantified claims in the whole README, and they are modest.

Woodpecker runs with SQLite as database by default, and requires around 100 MB of RAM for the server and 30 MB for the agent at runtime in idle mode.

So the default installation is a single-node one with no external database to run. That is the single biggest reason to pick this engine, and it has a build consequence that the Makefile makes explicit.

STATIC_BUILD ?= true
ifeq ($(STATIC_BUILD),true)
	LDFLAGS := -s -w -extldflags "-static" $(LDFLAGS)
endif
CGO_ENABLED ?= 1 # only used to compile server

CGO is on, and the comment says it is only used to compile the server. The reason is in the dependency list, where the SQLite driver is a cgo binding and the Postgres driver is not.

The consequence is that the server build needs a C toolchain for the SQLite binding while the agent does not, and the Makefile's STATIC_BUILD default of true adds -extldflags "-static" to the link flags either way. If you are producing artefacts for distribution or for a scratch container, that asymmetry is the thing to plan around rather than the RAM figure.

Plugins are separate processes, via HashiCorp's library

The plugin story is one sentence in the README and a dependency in the manifest.

Woodpecker can be extended via plugins. The plugin overview website helps browsing available plugins, and it combines both plugins by the Woodpecker core team and community-maintained ones.

go.mod lists HashiCorp's plugin library as a direct dependency, but the README does not say how the plugins on the overview site are executed.

Plugins are also a supply-chain surface: each step in a pipeline can be a binary you did not build, maintained by someone you did not choose, pinned to a version you have to track.

The README is honest that the index is mixed rather than presenting one support tier. It does not say which plugins are audited.

The consequence is that the plugin is where your pipeline's trust boundary sits, and the index tells you a plugin exists without telling you how much to trust it. Check the maintainer on the individual plugin rather than the fact that it appears on the overview site.

The version string comes from a tag, a branch, or a SHA

The Makefile derives its own version, and the logic is worth reading because it tells you what a version in a log actually means.

VERSION ?= next
VERSION_NUMBER ?= 0.0.0
CI_COMMIT_SHA ?= $(shell git rev-parse HEAD)

# it's a tagged release
ifneq ($(CI_COMMIT_TAG),)
	VERSION := $(CI_COMMIT_TAG:v%=%)

Then, when there is no tag, the version becomes the word next with the first ten characters of the commit appended. And there is a second branch for release branches: if the branch name starts with `release/v`, the version becomes the branch suffix with the short SHA appended.

The version is then compiled in.

LDFLAGS := -X go.woodpecker-ci.org/woodpecker/v3/version.Version=${VERSION}

There is also a container escape hatch. If the first argument to make is `in_docker`, the rest of the arguments are reinterpreted as a make target and the build runs inside a container instead of on your host.

The consequence is that there are three classes of version string. A release produces a clean number with the tag prefix stripped, a development build produces something containing a commit hash, and a release-branch build produces a hybrid. That is genuinely useful for tracing which binary ran a pipeline, and it means a version you read in a log is not necessarily a version you can go and download.

Seven lint configurations, and a tool that audits the CI itself

The repository root is where this project tells you what it holds itself to, and the list is long.

There is a spell checker configuration, an editor config plus a separate checker for it, a Go linter configuration, a Dockerfile linter, a Markdown linter, a YAML linter, a Prettier configuration with its own ignore file, and a pre-commit configuration. Three further files are ignore lists for other tools: one for a link checker and one for a vulnerability scanner, plus a configuration for mock generation.

The one that stands out is `checkmake.ini`.

checkmake is a linter for Makefiles, and this repository builds through a Makefile.

There is also a directory named for the tool itself, holding Woodpecker's own pipeline definitions, so the engine builds itself.

The consequence is that the tooling budget here is large and mostly automated. For a contributor that means pre-commit will run a substantial stack before anything reaches review.

Two licences, split by directory, with per-file headers

The License section is three sentences and it describes a licence split rather than a single grant.

Woodpecker is Apache 2.0 licensed. The source files have a header indicating which license they are under and what copyrights apply. Everything in `docs/` is licensed under the Creative Commons Attribution-ShareAlike 4.0 International Public License.

So the code and the documentation are under different terms, and the mechanism is a header in each source file plus a directory-level grant for docs/.

The ShareAlike term on the documentation is the part with a consequence. It is a copyleft licence, so redistributing the documentation requires the same licence, and it is a different licence family from the permissively licensed code next to it.

The consequence for a reader is that the split is deliberate and visible rather than an accident of a badge. If you are vendoring the source you are on Apache 2.0. If you are reproducing or adapting the documentation you are in a different regime, and the header in each file is the thing to check.

A Drone dependency survived the fork, and so did the plugin format

Woodpecker is a fork of Drone, and the dependency list is honest about what that means in practice.

Among the direct requirements is a Drone-owned module for environment variable substitution.

So one dependency from the upstream project is still called directly. The fork did not rewrite everything; it kept what worked.

The rest of the list describes the shape of the thing. There are SDKs for Gitea, for Forgejo and for GitHub, plus dedicated clients for Bitbucket and for resolving a VCS URL, which is the forge matrix stated as imports rather than as documentation. There is a Go web framework and a Swagger toolchain, plus a separate OpenAPI library, kin-openapi. There is an expression language, expr-lang/expr. There is a shell escaping package, which is the piece you would want present if the engine is generating shell commands on your behalf.

And there are more modules hosted on Codeberg, two from the 6543 account and the Forgejo SDK from mvdkleijn, alongside the fact that the module path itself is a vanity import on a domain the project owns.

The consequence is that this is a project that has consolidated its own infrastructure, and that the dependency list tells you the platform support story more precisely than the documentation does.

What Woodpecker cannot do, and what it leaves you owning

Five limits, and they are the ordinary consequences of a small, extensible engine.

It cannot protect you from its plugins. Plugins are maintained by the core team and by the community, mixed in one index. Each one is a step in your pipeline and a binary you did not build.

It cannot give you a uniform build. The server needs CGO for SQLite and the agent does not, so the server needs a C toolchain to build.

It cannot tell you which version a development build is. The version string is derived from a tag, a release branch name or a commit SHA, which is excellent for tracing and means a version reported in a log may not correspond to any downloadable release.

It leaves the database choice to you. The documented default is SQLite, go.mod also carries MySQL and Postgres drivers, and the README points to installation instructions for the other options rather than describing a clustered topology here.

And it cannot give you one support tier across the plugin ecosystem. The README's framing is that the index combines core-team and community plugins, and it makes no promise about which is which beyond the maintainer names.

Editorial conclusion

Adopt Woodpecker when you want a small-footprint CI engine you can run against SQLite on one box, because that is the deployment the documentation leads with and the measured idle cost is a hundred megabytes for the server and thirty for the agent. Do not adopt it expecting the plugin ecosystem to be uniformly maintained, since the plugin index deliberately mixes core-team and community plugins and nothing in the repository separates their support status. Before you plan a build pipeline, check two things. The server is compiled with CGO enabled because SQLite needs it, so building it needs a C toolchain while the agent does not. And the version string is derived from a tag, a release branch name or a commit SHA, which is useful for tracing a build and means a version you read in a log may not exist as a release.

Frequently asked questions

Official sources

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