PRD — FlareDispatch

BYOC (Cloudflare) CI/CD that offloads the expensive half of CI from GitHub Actions onto a Cloudflare stack — bring your own Cloudflare account, wrangler deploy the reusable typed runs into it, done in under an hour.

Problem

GitHub Actions is excellent as a trigger and a PR gate, and fine for cheap jobs (lint, type-check, unit). It is a poor fit for the heavy half of CI:

• Per-minute billing on slow work. Playwright e2e suites, acceptance tests against a running app, large sharded matrices, and long security scans are exactly the jobs that consume the most GHA minutes — and GHA minutes are expensive relative to raw serverless compute.
• Hard ceilings. A 6-hour job limit, actions/cache at a 10 GB cap with eviction, actions/upload-artifact with a fixed 90-day retention.
• Fan-out is awkward. Matrix builds are capped and coarse; there is no scale-to-zero between runs.

Teams work around this with self-hosted runners (which they must operate and secure) or by simply eating the bill. Neither is good.

Who needs this

Not for: teams whose CI is already cheap and fast (lint + unit only) — there is nothing to offload.

Value proposition

1. Lower cost on heavy CI. Per-execution compute is billed at CF Container rates (per vCPU-second, scale-to-zero) instead of GHA per-minute. Worked estimates and the head-to-head with GHA list pricing are in 06-cost.
2. No platform ceilings. Multi-step Workflows have no 6-hour limit; R2 cache and artifacts have no 10 GB cap and user-controlled retention. See 01-architecture § Platform limits.
3. Cheap, wide fan-out. Workflows createBatch spawns up to 100 children per call, 50,000 concurrent instances per account, scale-to-zero between runs. See 01-architecture § Fan-out model.
4. You own the runs. Runs are typed Effect programs — composable steps, tagged errors, exhaustive matching, retry/Schedule combinators — not stringly-typed YAML. Fork them, vendor-edit them, unit-test them without booting a container. See 02-runs and 03-dsl.
5. BYOC, no new dashboard. Every code path assumes “deployed into the user’s own Cloudflare account” — bring-your-own-Cloud, no operator runs it for you. Status reports back as a GitHub Check Run — the existing PR UI is the UI. See 04-gha-integration § Check-runs callback.
6. Three trigger modes, one Dispatcher. Action mode interleaves with existing GHA jobs; Webhook mode (opt-in) runs autonomously on GitHub events with zero GHA minutes; Schedule mode fires runs on a wall-clock cadence via Cloudflare Cron Triggers — nightly PR-review sweeps, weekly release notes, scheduled dependency scans. See 04-gha-integration.
7. Agentic PR review in-Worker, BYOK-or-keyless. pr-review is a first-class run — configurable single- or multi-agent (pr-review.agents): an @effect/ai modelGateway capability picks the backend from CONFIG_KV without redeploy — Workers AI catalog incl. DeepSeek reasoners (@cf/… or deepseek/…, binding-as-auth or BYOK, the workers-ai route), Anthropic-via-AI-Gateway (BYOK), or Bedrock-via-AI-Gateway (OIDC → STS → SigV4, no long-lived AWS key) — and a dispatch can override the model/region/role per call for model bake-offs. The diff is capped to the model’s context window; the review posts as a scannable summary table + per-finding headings with GitHub blob links, and re-reviews auto-resolve fixed findings. See 02-runs and 07-trust-model.
8. Federated cloud credentials, no long-lived keys — shipped. The Dispatcher self-issues OIDC tokens at a stable JWKS endpoint (/.well-known/jwks.json); runs federate against AWS STS via sts:AssumeRoleWithWebIdentity (awsAssumeRole) for short-lived, per-execution credentials. pr-review’s bedrock backend (#111) is the worked example: it mints AWS creds by OIDC, then SigV4-signs Bedrock InvokeModel through the AI Gateway — no long-lived AWS access key ever lands in Worker Secrets. GCP STS / HashiCorp Vault federation extend the same primitive. See 03-dsl § oidc and 05-byoc § AWS federation trust policy.

What a run is

A run is a typed, named Effect-TS program with:

• A Schema-defined input contract (what the caller sends).
• A Schema-defined output contract (what gets posted back).
• A sequence of steps, each mapped to a CF Workflow step, composed via Effect.gen.
• Access to a fixed set of capabilities — sandbox, browser, cache, artifact, io, config, github — and the primitives built on them (workspace, installCached, sharded, …) so the run carries only its own logic, not the boilerplate.

Runs are not opaque — they are TypeScript files in the user’s repo. The shipped runs are the starter library; the DSL is the contract. The DSL is layered: capabilities → primitives → runs (recipes), so common CI shapes are written once and reused. Full catalog in 02-runs; DSL surface and the layering in 03-dsl.

Operating model — BYOC (Cloudflare)

flowchart LR
  GHA[GitHub Actions<br/>trigger + cheap jobs] -->|HMAC POST<br/>/v1/dispatch| W[Run Worker<br/>in your CF account]
  APP[GitHub App webhook<br/>autonomous trigger<br/>opt-in] -->|App-signed<br/>/v1/webhooks/github| W
  CRON[Cloudflare Cron Trigger<br/>scheduled cadence] -->|scheduled handler| W
  W --> WF[CF Workflow<br/>durable orchestration]
  WF --> SB[Sandbox / Container<br/>test execution]
  WF --> BR[Browser Rendering<br/>Playwright]
  WF --> R2[(R2<br/>cache + artifacts)]
  WF --> D1[(D1<br/>execution metadata)]
  W -->|check-run API| GH[GitHub Checks tab]

All three arrows are live at HEAD. Webhook mode (the /v1/webhooks/github receiver) is shipped but opt-in / off by default: a deploy without GITHUB_WEBHOOK_SECRET returns 503 on that route, so it fires only once you set the secret — it does not run on every push by default. The Action-mode (HMAC) and Schedule-mode (Cron Trigger) paths are always on.

A team installs runs by:

1. Forking or cloning a template repo.
2. wrangler deploy the Dispatcher into their own Cloudflare account.
3. Visiting the Dispatcher’s /v1/github/install/new to create their own GitHub App via the App Manifest flow (the project ships a manifest template, not a shared App on the Marketplace; the chooser there picks personal-account vs org ownership), then stashing the App’s id / private key / webhook secret into Workers Secrets and installing that App on their org/repos.
4. Adding uses: openhackersclub/flare-dispatch-action@v1 to their workflow (Action mode), or just letting their App’s webhook fire runs (Webhook mode — opt-in, enabled by setting GITHUB_WEBHOOK_SECRET).

After that, each PR fires runs against the team’s own Cloudflare bill. The project supplies the runs, the GHA Action, the Effect-TS DSL packages, and the App manifest template. The team supplies the account and the App — both are BYOC; nothing routes through an openhackersclub-operated control plane. Full deploy guide in 05-byoc; trust posture in 07-trust-model.

Non-goals

• Replacing GitHub Actions. GHA remains the trigger, PR gate, and home for fast jobs. Runs are an offload target, not a control plane.
• Hosted SaaS in v1. Every code path assumes “deployed into the user’s Cloudflare account.” A SaaS edition is possible later; it is not a v1 constraint we design around.
• A new dashboard / UI. GitHub Check Runs are the UI. Logs and artifacts are served via R2 signed URLs linked from the check summary.
• Secrets management product. Workers Secrets is sufficient; runs don’t reinvent it.
• Generalized workflow engine. Runs are for CI-shaped work. For durable business workflows, use Trigger.dev or Temporal.

Success criteria

V0 — the slice that proves the model, a pnpm test executing in CF Sandbox reporting green/red to a PR check — has shipped. Implementation has continued out of strict V order: 11 runs are registered and live at HEAD — offload-test, cdp-acceptance, deploy-smoke, matrix-fanout, playwright-demo, playwright-e2e, pr-review, product-demo, refresh-fixtures, spec-drift-pr, and ci-triage-pr (this is the sorted set /health returns). Among them, agentic PR review (pr-review, configurable single- or multi-agent) is a first-class product surface, and Webhook mode is shipped (opt-in). Still incremental and independently shippable: the remaining roadmap is the cache/artifact polish, the human-in-loop surface, broader security scans, and V4 polish (OpenTelemetry, retention, an init CLI). See pm/plan § Implementation status.

Project-management detail lives under pm/: the phased roadmap — scope, runs shipped, and the exit criterion that closes each phase — and the 7-PR V0 build sequence are both in pm/plan.md.

Relationship to Cloudflare Workers CI/CD

Cloudflare ships its own CI/CD — Workers Builds — but it solves a different problem at a different layer. Workers Builds (and the GitHub Actions integration the same docs describe) automates building and deploying Worker code on a git push: it pushes your Worker to production, manages deploy credentials, and keeps deployments consistent across a team. It does not run your repository’s test suites — there is no integrated test runner and no arbitrary-suite execution.

FlareDispatch is not a deploy pipeline. It is a test-compute offload: it executes Playwright e2e, acceptance suites, sharded matrices, and security scans inside CF Containers / Browser Rendering / Workflows and reports the outcome as a GitHub Check Run. The two are complementary, not competing:

• Workers Builds deploys FlareDispatch. The FlareDispatch Dispatcher is itself a Worker, so Workers Builds is a perfectly good way to deploy and keep it updated — see 05-byoc.
• FlareDispatch runs the tests Workers Builds doesn’t. Workers Builds has no opinion about your repo’s heavy test suite; FlareDispatch is exactly that opinion.
• Same platform, different layer. FlareDispatch is built on the same Cloudflare primitives Workers Builds deploys to — Workers, Workflows, Containers, Browser Rendering, R2, D1 — but it is an orchestration plane for CI work, not a code-deployment pipeline.

Comparison with adjacent options

Spec index