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
| Event | Where | Runs | Default |
|---|---|---|---|
| Pull request (any branch, forks included) | GitHub: checks.yml | pnpm check, pnpm test:unit, pnpm test:smoke, pnpm build, pnpm test:e2e | On |
Push to main | GitHub: checks.yml | The same checks | On |
Push to main | Workers Builds on web | vp run deploy | Off 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.
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
stagingbranch 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
| Yours | The 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 deployed | The 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
- Checks and E2E
- Production Deploys
- Troubleshooting
- Database Migrations
- Custom Domains
- Backups and Recovery
Env variables, and how DATABASE_URL differs from the other keys, are covered in Environment Variables.
Next: Checks and E2E →