Woodpecker CI 3.18 migrates its log storage and stops leaking matrix variables into plugins
Version 3.18 of the self-hosted Woodpecker CI platform ships a database migration that reworks log storage — a backup and a maintenance window are recommended before upgrading. It also tightens security: additional and matrix environment variables are no longer injected into plugins automatically.
August 25, 2026. Woodpecker CI, the self-hosted CI/CD platform that works with GitHub, GitLab, Gitea, and Forgejo, publishes version 3.18. One database migration. That is the first thing an administrator should read in the release notes: log storage changes structure, and the migration can take time on heavily used installations.
The release has two faces. On one side, a storage migration that demands a backup and a maintenance window; on the other, a welcome security tightening of what plugins can see of your environment secrets.
A log migration not to be taken lightly
The most structural change in 3.18 is invisible at first glance. Woodpecker reworks how it stores pipeline logs: the underlying storage now enforces one log entry per line, with a unique index. That is what drives the database migration, and what makes it potentially slow on an installation that has accumulated lines for months.
The official guidance is unambiguous: take a backup before upgrading, and allow extra downtime while the migration runs. On an instance orchestrating dozens of repositories and years of builds, the rework can amount to a real maintenance window — not a routine docker compose pull.
In return, logs gain coherence. Step logs are returned in their proper line order, and a dedicated endpoint now lets you download a pipeline’s logs. For anyone who has ever had to reconstruct a failed build from interleaved lines, that is a concrete readability gain.
Fewer variables exposed to plugins
The security side is the most interesting for an SRE. Woodpecker tightens how plugins handle environment variables: additional and matrix variables are no longer injected automatically.
Concretely, a build or deploy plugin used to receive, by default, the pipeline’s entire environment context — including variables it had no reason to know. That is a classic leak vector: a compromised third-party plugin, or one that is simply chatty in its logs, could expose secrets or configuration values that were none of its business.
The new rule inverts the logic: nothing is injected unless requested. It is the least-privilege principle applied to environment variables, and exactly the kind of hardening that matters on a self-hosted CI/CD where you execute plugin code you have not audited line by line.
A gRPC protocol that refuses incompatible agents
Woodpecker also adds a guardrail on server–agent communication. A gRPC protocol version check now prevents an agent running an incompatible version from connecting to the server.
It is a quiet but useful change: a heterogeneous agent fleet — an up-to-date server with lagging agents — could produce failures that were hard to diagnose, the server accepting connections it only half understood. Rejecting incompatible agents explicitly makes the failure legible: the agent does not connect, rather than connecting and failing downstream.
Agents gain resilience in the same pass: reconnection attempts are now retried after a DeadlineExceeded error, on top of the already-handled Unavailable condition. On an unstable network, that removes false connectivity negatives.
The other adjustments that matter
The rest of the release is a set of targeted fixes that trace a steady product maturation.
- Manual pipelines with a custom message: you can now attach context to a manual trigger, to document why that run was started.
- Unique names enforced for services and steps in DAG pipelines — an end to silent collisions.
- Kubernetes backend: an option to disable the runtime class name setting, plus cluster-domain configuration instead of the default.
- GitLab integration: the full group path now serves as the identifier, which hardens nested organizations.
- Multi-forge: you can configure, per forge, which organizations are allowed to use the service.
The release also fixes Windows support — an internal Base64 decode command on the local backend, plus a fix for a bug that prevented multiple PowerShell cmdlets from running correctly — and updates a set of dependencies, from the Git plugin to the Docker CLI library and protobuf.
Where Woodpecker sits in self-hosted CI/CD
Woodpecker occupies a precise niche: a lightweight, self-hosted CI/CD that plugs into Gitea and Forgejo where Drone has stalled and Forgejo’s native Actions remain younger. Its value lies in simplicity — one binary, one agent, YAML pipelines — and a plugin model that avoids the complexity of GitLab runners.
The storage migration in 3.18 is a reminder of that choice’s cost: on a SaaS platform, log migration is invisible; on a self-hosted instance, you carry it yourself. That is the self-hosting contract, no more and no less. The release states it plainly, and that is to its credit: a clear warning beats a surprise in the middle of the night.
The environment-variable tightening, for its part, changes pipeline behavior in a concrete way. Before, a plugin received matrix and additional variables by default; now you must pass them explicitly. Any pipeline that relied on that implicit injection will need a review — that is the price of a safer default.
Passing a variable to a plugin now requires declaring it:
steps:
deploy:
image: woodpeckerci/plugin-docker-buildx
settings:
registry: ghcr.io
environment:
MATRIX_OS: "${MATRIX_OS}"Before 3.18, ${MATRIX_OS} was available without that declaration. The change is deliberately strict: everything a plugin sees must be named.
Upgrading safely is a short checklist:
- Back up the database first — the log-storage migration is the riskiest part of the release, and a full backup is what separates a slow migration from a lost history.
- Audit pipelines that relied on implicit variables — any step expecting
${MATRIX_*}or additional variables without declaring them will break. - Align your agents — the gRPC version check rejects incompatible agents, so upgrade agents alongside the server rather than piecemeal.
Step logs in their proper line order may sound trivial, but it fixes a real debugging pain. In concurrent pipelines, interleaved lines made it nearly impossible to reconstruct which step produced which output. Enforcing one log entry per line with a unique index lets the server guarantee ordering, and the new download endpoint hands you the raw log as a file you can archive next to a failed build’s artifacts.
The broader point is that a release like this rewards teams that treat their CI server as production infrastructure. The migration is predictable if you read the notes, and punishing if you do not.
Verdict
If you operate Woodpecker CI in production, treat this upgrade as planned maintenance, not a routine patch. Back up the database, schedule a window, and verify after migration that your pipeline logs read back correctly. The security gain — fewer variables exposed to plugins — is worth the window, but it is not worth skipping the backup.
If you are weighing Woodpecker against a SaaS forge, this release illustrates exactly the self-hosting trade-off: you gain control and least-privilege hardening, but you also inherit responsibility for storage migrations. That is a conscious choice — provided you never discover it at the moment of an upgrade.
The lesson fits in one sentence: on a self-hosted CI/CD, security lives as much in how plugins receive your variables as in how you back up your logs before a migration.