Workers Builds: integrated CI/CD built on the Workers platform

Workers Builds: an integrated CI/CD system on the Workers platform

Cloudflare introduced Workers Builds during 2024's Birthday Week as an open beta: a CI/CD workflow that lets developers connect a GitHub or GitLab repository to a Worker and have Cloudflare automatically build and deploy on every push. The service is part of the ongoing convergence between the Pages and Workers developer experiences, bringing Pages' integrated deployment pipeline to Workers. Building this system meant deciding between extending the existing Pages architecture or using the Workers platform itself as the foundation for a new control plane.

The system at a glance

The Workers Builds architecture has two main components:

• Client Worker: a RESTful API (built with Hono) backed by PostgreSQL, which stores build configurations that users create and manage through the dashboard.
• Build Management Worker: a pair of Durable Object (DO) classes that schedule and manage individual builds.

For the database connection, the team chose Hyperdrive to reach the PostgreSQL database securely over Cloudflare Access, with connection pooling and query caching handled automatically. While a more distributed data store like D1 was considered, the relational nature of the data model — builds belong to Workers, Workers belong to accounts — and the need for consistent build metadata to manage queues made a centralized, failover-ready database the right fit.

The connection layer for GitHub/GitLab account linking and push-event ingestion was reused from Pages unchanged. The remaining challenge was running builds with low latency, tracking status through the full lifecycle, and storing logs securely for the long term.

Scheduling with Durable Objects

Each build gets its own Build Buddy DO instance, which keeps the system scalable and responsive: no build's operation can block another build or the scheduler, and builds start with minimal latency. The Scheduler DO uses Durable Objects Alarms to trigger every second, pulling up build configurations that are ready to run and creating a Build Buddy instance for each one.

On creation, the Scheduler calls startBuild() on the new instance. The method gathers the metadata and secrets needed for the build, then kicks off a containerized job on Cloudflare's container platform, which is not yet public but expected soon. As the container runs, it reports status updates and log output back to the Build Buddy.

Status tracking and log storage

The Build Buddy handles incoming status updates — initializing, success, or termination by the user — and writes them to the database via Hyperdrive so the dashboard reflects the current state of each build.

Build logs are flushed from the container to the Build Buddy every second and stored in DO storage. This setup lets the same API serve both live streaming and historical log views, and efficiently multicast logs to multiple clients. Alarms on the Build Buddy check startup health and terminate builds that exceed the 20-minute limit.

Performance and observability

The control plane runs distributed, but most requests should be served close to the primary database in the western US. For the Client and Build Management API Workers, Smart Placement with location hints ensures requests run near the database, reducing round-trip time.

For troubleshooting, the team adopted Workers Logs early, working with the Workers Observability team. Logs appeared in the dashboard with minimal setup. A tagging library adds metadata such as the git tag of the deployed worker, letting the team filter logs by release. Errors on the Client Worker are logged with structured JSON, making it possible to filter by any field in the Workers Logs view.

Additional platform leverage

Several other Workers platform features support the system:

• R2-backed build caching is coming soon, storing build artifacts like package dependencies and output so subsequent builds can skip redownloading from NPM or rebuilding from scratch.
• Testing runs on Vitest and workerd, the same runtime as production. Unit tests use the runInDurableObject stub from cloudflare:test to exercise Scheduler DO methods directly; integration tests use SELF.fetch() to cover Hono endpoints and database queries.
• Analytics Engine underlies the metrics collection, displayed on Grafana dashboards.
• JavaScript-native RPC, available in Workers since April 2024, keeps the scheduler-to-build-buddy interaction clean: the Scheduler calls startBuild() directly on the DO instance rather than setting up fetch routes and HTTP requests between the two DO classes — which means less boilerplate and better ergonomics when wiring DO instances together.

Workers Builds demonstrates that the platform has matured to the point where large subsystems could reasonably be reconsidered: instead of running a Kubernetes cluster for build management, the team could rely on Durable Objects' automatic failover and scaling. The scope of this project is worth noting — in laying out how the team designed their system, they showed the components are doing substantial work already, even while the platform continues to evolve with build caching and additional features on the near horizon.

Building Internal Tools on the Platform Itself

Workers Builds is a good example of the kind of complex, distributed system that can be assembled from Workers and Durable Objects, while remaining straightforward to reason about and to scale. Building this kind of tooling on the same platform the team maintains has real benefits. Acting as the "Customer Zero" for internal products lets the team identify friction firsthand, and it provides a way to test new features in a realistic environment before they reach the wider developer community.

That experience often feeds back into the platform's roadmap. For instance, the Builds team acted as internal testers and collaborators for Workers Logs and for private network support in Hyperdrive, both of which were released during Birthday Week. The same process is underway for the forthcoming container platform.

Where the Platform Is Heading

It is worth remembering that this type of application would have been considerably more difficult to build on Workers just a few years ago. The platform has matured, and the scope of what can be built on it keeps expanding. The broader point is that developers have an increasing number of options for building complex applications without managing traditional infrastructure, and the hope is that Workers Builds provides a way to automate software delivery without adding another layer of configuration to maintain.

If you want to try it out, the documentation covers how to get your first project deploying through Workers Builds.