Deployment

What runs on each pull request and push: GitHub checks, and production deploys in Cloudflare Workers Builds. What is on by default, and which files are yours.

GitHub Actions runs the checks and the e2e suite on every pull request and on pushes to main, with no setup. Production deploys to your own Cloudflare account run in Cloudflare Workers Builds, Cloudflare's Git integration. They stay off until you connect the Worker to the repository in the Cloudflare dashboard, so a fresh fork stays green.

The kit deploys with vp run deploy only (it runs void deploy --platform cloudflare), to the account your API token belongs to. Running void deploy directly deploys without the admin's audit reader (Read the Audit Log).

The kit requires Workers Paid ($5/month) to run reliably: Free can't send email to your users, and password hashing can exceed Free's CPU limit (Production Deploys).

What Runs When

EventWhereRunsDefault
Pull request (any branch, forks included)GitHub: checks.ymlpnpm check, pnpm test:unit, pnpm test:smoke, pnpm build, pnpm test:e2eOn
Push to mainGitHub: checks.ymlThe same checksOn
Push to mainWorkers Builds on webvp run deployOff until you connect web
  • Deploys don't wait for the GitHub checks. Workers Builds starts on the push. Make the checks required in branch protection on main, so only passing code gets there (Production Deploys).
  • A new push to a pull request cancels its previous check run.

How It Fits Together

There is one environment, production: the main branch, the Worker web, and apps/web/void.lock.json. Your first deploy creates the lock file and you commit it. From then on Void picks the Worker and its resources (Hyperdrive config, KV, R2, queues) from it.

Deploy credentials run migrations and bind the Worker. Runtime connects through Hyperdrive, R2, queues and Stripe; cron sweeps pending jobs.Click to expand

Build credentials stay in the deploy environment. Runtime secrets belong to the Worker; runtime database access uses Hyperdrive, never a DATABASE_URL Worker secret. Resources are in your Cloudflare account; Postgres is with your chosen provider.

Why Workers Builds

  • Configured in the dashboard: no deploy workflow, no Cloudflare token in GitHub.
  • Cloudflare reports back: a check run on each commit and a comment on the pull request.
  • Tradeoffs: deploys don't wait on the GitHub checks (branch protection is the gate), and the build settings live in the dashboard, not in the repository. Write them down for your team.

Staging and Previews

The kit doesn't ship a staging environment or branch previews. Void has no named environments: the Worker and its resource IDs come from the committed void.lock.json.

  • A second Worker connected to the same repository deploys with production's resource IDs, including the production database.
  • A staging branch with its own lock doesn't hold either: merges move the lock between branches.

For staging, use a separate repository (or clone) with its own void.lock.json, database and Cloudflare account, and deploy it the same way.

Files You Own vs Files the Kit Owns

YoursThe kit's (avoid editing; updates land here)
Workers Builds settings on web, and its build variables and secrets.github/workflows/checks.yml, .github/actions/setup/action.yml
apps/web/void.lock.json, once you've deployedThe deploy and preview tasks in apps/web/vite.config.ts, tooling/scripts/src/preview-env.mjs
Worker secrets (SITE_URL, PRODUCT_NAME, BETTER_AUTH_SECRET, your keys)apps/e2e/playwright.config.ts, apps/e2e/tests/utils/**, apps/e2e/tests/smoke/**
Branch protection rules, your e2e specs (apps/e2e/tests/<area>/)

Topics

  1. Checks and E2E
  2. Production Deploys
  3. Troubleshooting
  4. Database Migrations
  5. Custom Domains
  6. Backups and Recovery

Env variables, and how DATABASE_URL differs from the other keys, are covered in Environment Variables.


Next: Checks and E2E →