Managed Woodpecker CI agents for builds that outgrow one box

A Woodpecker CI agent connects to your Woodpecker server over gRPC, pulls workflows and runs them on Docker, Kubernetes or the local shell. Woodpecker has no hosted offering of its own: you run the server and the agents. The agent bundled in the upstream compose file runs on the same box as the server, and that box sets the pace of every build. For a compile-heavy codebase, the agent machine is the bottleneck.

Status: Woodpecker CI is on the cirunner.dev roadmap. Our early access starts with GitHub Actions and GitLab CI. This page describes how Woodpecker support will work.

Where a Woodpecker agent runs short

• One agent with WOODPECKER_MAX_WORKFLOWS=2 splits its cores and memory between two builds, and a third waits.
• Workflows on the docker backend share one Docker daemon, its images and its disk.
• arm64 or riscv64 builds need a separate agent on matching hardware.
• GPU tests need a GPU host that sits idle most of the day.
• On ci.codeberg.org the shared agents build linux/amd64 only.

Running your own Woodpecker agents

The Woodpecker agents guide has the full setup. The parts that take time:

• Expose the server's gRPC port behind TLS so remote agents can reach it, and set WOODPECKER_GRPC_SECURE=true on the agent.
• Pick an authentication model: a shared system token in WOODPECKER_AGENT_SECRET, or per-agent tokens from Settings, Agents, which you can revoke one at a time.
• Persist /etc/woodpecker/agent.conf, or each restart registers a new agent.
• Route with labels such as platform=linux/arm64 and custom ones from WOODPECKER_AGENT_LABELS.
• Scale with the woodpecker-ci autoscaler, which the Woodpecker docs call not yet feature-complete, or keep a fixed pool.

The docker backend mounts the host's Docker socket into the agent, so pipelines get a path to root on that host. You run those agents on dedicated VMs and keep them patched.

How managed Woodpecker agents will work

1. You create an agent in your Woodpecker UI (admin, organization or user level) and give us its token, plus the gRPC address of your server.
2. You choose a machine in the configurator: more cores and memory than your current agent host, x86 or ARM, a GPU if you need one.
3. We start agents in single-workflow mode on fresh VMs with the labels you pick. Your pipeline routes to them with a labels: block, for example gpu: nvidia or platform: linux/arm64.
4. After the workflow ends, we destroy the VM. A build cache persists between workflows so the next one does not pull and compile from scratch.

Your server, forge integration and pipeline files stay as they are. Billing is per compute minute.

Woodpecker agent options compared

Who managed Woodpecker agents fit

Good fit:

• Teams running Woodpecker with Forgejo, Gitea or GitLab whose builds take tens of minutes: C, C++, Rust, Android, embedded.
• Projects that want arm64 or GPU agents without buying the hardware.
• Codeberg users with ci.codeberg.org access who need more than the shared amd64 agents.

Not a fit:

• Pipelines that finish in a few minutes on the agent you already have.
• Workflows that need the local backend on a specific machine, such as hardware-in-the-loop tests.

FAQ

Are there managed Woodpecker agents?

The Woodpecker project does not sell hosted agents. cirunner.dev has managed Woodpecker agents on its roadmap and does not run them yet. Vote for them on the early-access form.

How do I add a Woodpecker agent to an existing server?

Create an agent under Settings, Agents, copy its token, and start woodpecker-agent with WOODPECKER_SERVER set to the server's gRPC address and WOODPECKER_AGENT_SECRET set to the token. The agents guide has compose and systemd examples.

Can a Woodpecker agent connect to several servers?

No. One agent process connects to one server. Run a separate agent per server.

Is Woodpecker a fork of Drone?

Yes. Woodpecker forked from Drone 0.8 in 2019 and stays under the Apache 2.0 license. The pipeline formats have diverged since. See the Drone runner page if you still run Drone.