# 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.

*Canonical: https://makerkit.dev/docs/void-cloudflare/deployment/overview*

---

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](../audit/reading-the-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](./production#before-you-start)).

## 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](./production#protect-main)).
- 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.

{% img src="/assets/images/docs/void-cloudflare/deployment-architecture.svg" width="600" height="1330" alt="Deploy credentials run migrations and bind the Worker. Runtime connects through Hyperdrive, R2, queues and Stripe; cron sweeps pending jobs." /%}

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

| 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

1. [Checks and E2E](./checks-and-e2e)
2. [Production Deploys](./production)
3. [Troubleshooting](./troubleshooting)
4. [Database Migrations](./migrations)
5. [Custom Domains](./custom-domains)
6. [Backups and Recovery](../operations/recovery)

Env variables, and how `DATABASE_URL` differs from the other keys, are covered in [Environment Variables](../configuration/environment-variables#deployed-environments).

---

**Next:** [Checks and E2E →](./checks-and-e2e)
