Skip to content
SiteSwarm Platform Documentation

Cloudflare Workers Builds Evaluation

Cloudflare Workers Builds vs. GitHub Actions Deployment Orchestration Evaluation

Source Issue: #534
Status: reference (Point-in-time evaluation of rejected alternative; intentionally excluded from canonical specification distillation)

1. Context & Objective

During ongoing optimization of SiteSwarm’s continuous integration and edge deployment pipelines, we evaluated Cloudflare Workers Builds (Cloudflare’s native Git-connected CI/CD runner for Workers) to determine:

  1. What Workers Builds build minutes measure and what resource/concurrency limits apply across Cloudflare account tiers.
  2. Whether Workers Builds can replace SiteSwarm’s existing GitHub Actions deployment workflows (preview-deploy.yml, staging-deploy.yml, and production-promote.yml) for monorepo Worker deployments.

Because the evaluation concluded that SiteSwarm should retain its existing GitHub Actions orchestration rather than migrating to Workers Builds, this document is recorded with status: "reference" as a permanent point-in-time engineering reference that does not require distillation into docs/{architecture,runbooks,business}/.

2. What Are Cloudflare Workers Build Minutes?

Workers Builds is Cloudflare’s built-in CI/CD service that links a GitHub or GitLab repository directly to a Cloudflare Worker. When commits are pushed or pull requests are opened, Cloudflare provisions an ephemeral build container, installs workspace dependencies, runs the configured build command, and deploys the compiled Worker (or a branch/PR preview).

Build minutes measure the wall-clock execution duration of those ephemeral build containers across an entire Cloudflare account per monthly billing cycle.

2.1 Resource Allocations & Concurrency Quotas

Resource / Quota Workers Free Tier Workers Paid Tier
Included Monthly Build Minutes 3,000 minutes / month 6,000 minutes / month (metered overage per minute thereafter)
Concurrent Builds (Account-Wide) 1 concurrent build 6 concurrent builds
Build Timeout Ceiling 20 minutes per build 20 minutes per build
Build Container Compute 2 vCPU, 8 GB RAM 4 vCPU, 8 GB RAM
Build Container Ephemeral Disk 20 GB 20 GB
Deploy Hook Rate Limit 10 builds/min per Worker (100/min per account) 10 builds/min per Worker (100/min per account)
Build Log Retention 90 days 90 days

3. Monorepo Support & Native PR Previews in Workers Builds

Cloudflare Workers Builds provides two features aimed at multi-app repositories and pull request workflows:

  1. Monorepo Build Watch Paths:

    • Each Worker in a monorepo can be connected individually to the same GitHub repository in the Cloudflare Dashboard, with its Root Directory pointed at apps/<app-slug>.
    • Build Watch Paths allow each Worker to specify inclusion globs (e.g., apps/app-bakery/*, packages/*) and exclusion globs so pushes only trigger builds for affected Workers.
    • Limitation: Watch paths are managed per-Worker in the Cloudflare Dashboard rather than declaratively inside wrangler.jsonc, and Cloudflare bypasses watch-path filtering (forcing a build across connected Workers) when a push exceeds 20 commits or 3,000 changed files.

  2. Native Worker Previews & Custom Domains:

    • Workers Builds automatically generates both a stable branch/PR preview URL and an immutable deployment-hash URL, including support for custom preview domains and automatic PR status comments.

4. Architectural Comparison: Why SiteSwarm Retains GitHub Actions

While Workers Builds handles standalone Worker compilation well, it cannot serve as a 1:1 replacement for SiteSwarm’s GitHub Actions pipelines (preview-deploy.yml, staging-deploy.yml, production-promote.yml) without sacrificing core governance and verification guarantees.

Platform Capability SiteSwarm GitHub Actions Orchestration Cloudflare Workers Builds (Native Git CI)
Opt-In PR Preview Gating Triggered only when the preview-deploy label is applied to a non-draft PR (or via workflow_dispatch). Triggers automatically on every PR commit matching watch paths; no native GitHub label filtering.
Pre-Deploy Governance Latch (Gate) staging-deploy.yml and production-promote.yml run scripts/verify-commit-checks.ts to block deployment until Gate and Staging Gate pass. Triggers directly from Git push webhooks without waiting for external GitHub Actions check suites (Gate or governance/two-stage-review) to pass.
Scheduled & Debounced Batching staging-deploy.yml runs on a 12-hour cron with a 4-hour debounce window (scripts/staging-debounce.ts) to batch commits. Event-driven on push only; no native cron batching or commit-window debouncing.
Dynamic Resource Auto-Provisioning & wrangler.json Mutation Pre-deploy scripts dynamically resolve/create per-PR SESSION KV namespaces and D1 databases, apply D1 migrations, strip send_email bindings on previews, and drop undeployed service bindings (preventing Cloudflare error 10143). Expects declarative wrangler.jsonc targets or requires embedding Cloudflare API provisioning tokens and mutation scripts directly into each app’s build command.
Post-Deploy Verification Chaining Immediately chains into acceptance-test.yml for dual-endpoint health probes (workers.dev + custom domain), Playwright E2E tests via Cloudflare Browser Run CDP, @axe-core/playwright WCAG 2.1 AA audits, and R2 screencast capture, posting a single consolidated matrix comment. Terminates after Worker script upload; cannot orchestrate post-deploy Playwright suites, Terraform plans, or unified multi-app PR tables.
Ephemeral Resource Teardown preview-teardown.yml automatically deletes -preview-pr-<N> Workers and ephemeral KV namespaces when a PR closes. Previews are scoped as environments on the parent Worker rather than lifecycle-managed multi-worker topology with custom KV teardown hooks.
Shared Package Blast Radius scripts/change-detector.ts supports --canary-on-platform-wide and controlled matrix parallelism. Modifying packages/components or packages/theme triggers every connected Worker simultaneously across the 6-concurrency-slot ceiling, running isolated pnpm install + build containers per app.

5. Conclusion & Operational Recommendation

  1. Retain GitHub Actions (on Blacksmith runners) for Monorepo Orchestration:
  2. When to Consider Workers Builds:
    • If an isolated, single-tenant utility Worker is ever spun out into a standalone repository outside the SiteSwarm monorepo—where label gating, Terraform, D1/KV auto-provisioning, and Playwright/WCAG chaining are unnecessary—Workers Builds provides a zero-config push-to-deploy option using Cloudflare’s included monthly build minutes.

Decisions Intentionally Deferred

  • Hybrid Build Offloading via Deploy Hooks: We intentionally defer investigating a hybrid model where GitHub Actions runs Gate and change detection and then triggers Cloudflare Deploy Hooks per Worker, because GitHub Actions still needs to run post-deploy Playwright/WCAG acceptance gates and dynamic KV/D1 binding resolution.