Deployment

Deploy pipeline

How a push or a pull request reaches Cloudflare, and what a deploy needs from you.

Both applications deploy to Cloudflare Workers, independently, from the same repository, and GitHub Actions is what deploys them. There is no git connection on the Cloudflare side and no build or deploy setting in the Cloudflare dashboard. The whole path is one workflow file in your repository, and you own it.

Which event deploys what

EventRuntime ContextWhat runs
Push to development / stagingthat nameresources → build → migrate (web only) → varlock-wrangler deploy
Push to mainproductionthe same — but see below
Pull request, whatever it targetspreviewresources and Preview Database → build → migrate it (web only) → varlock-wrangler preview --name pr-<n> --json
Pull request closed, merged or not—wrangler preview delete --name pr-<n> on each application's preview Worker, then delete the Preview Database
Daily, and on demand—pnpm previews:cleanup --yes: delete what a closed pull request left behind

A push or pull request that changes only paths in the paths-ignore list of .github/workflows/deploy.yml runs nothing, because it would ship nothing new.

A push whose code is exactly a merged pull request's head skips the checks for each application whose job passed on that head, and goes straight to the resources step. It still builds and deploys, since the build resolves the push's own Runtime Context. Any other push, such as a direct commit or a pull request merged while behind its target, runs every check first.

A draft pull request runs nothing until it's marked ready for review. A pull request labelled pr:skip-ci runs nothing at all, its closing included. Merge one without CI says when to use the label.

A pull request is preview whichever branch it targets. No branch name is read on one. The resources step comes first in every run that deploys: it finds each resource the context binds by name, creates the one that's missing, and updates apps/web's pool from DATABASE_URL. varlock-wrangler deploy and varlock-wrangler preview only bind what it found. Resources covers the step.

In NuxtStart itself, main is the production branch and deploys NuxtStart's own production. NuxtStart publishes its transformed downstream tree to published after the ordinary promotion, and the publication withholds NuxtStart's production values, so a push to your copy's main fails, naming a missing value, until you fill in your own. See Migration publication.

Pull request previews

A pull request does not get a Worker of its own. The workflow deploys it as a Cloudflare Worker Preview named pr-<n> on the preview Worker, <slug>-<app>-preview, which the first pull request's run creates. Its URL has the shape https://pr-<n>-<slug>-<app>-preview.<subdomain>.workers.dev, and the workflow posts it on the pull request.

The Preview carries its own code, values and bindings, and fires no cron. The preview Worker serves no deployment of its own, and no other Runtime Context is involved, so previews work before development deploys, after it, or without it. Adding pull request previews sets them up.

Origins. apps/*/.env.preview holds the preview Workers' own origins, and no pull request is served from them. Before the build, Decide whether this run can deploy puts pr-<n>- in front of each workers.dev origin in that file, so a pull request's apps/web preview links to the same pull request's site preview. The rewrite reads the file as text, so each origin has to stay a bare https://…workers.dev value.

Bindings. wrangler preview binds from the previews block of the generated wrangler config and never falls back to the top level. mirrorBindingsIntoPreviews in packages/layer-base/shared/utils/env.ts fills that block with the bindings the build resolved. Every open pull request shares preview's bucket and content database, and each apps/web Preview binds a pool of its own.

Preview Database. apps/web's Preview is backed by a database of its own: the Neon branch pr-<n> of preview's Neon project, behind the Hyperdrive configuration <slug>-web-preview-pr-<n>, with caching off so a write is read back at once. The resources step creates both on the pull request's first run and reuses them on every later push. The branch starts from the project's empty default branch, and Migrate the database applies the pull request's own committed migrations to it before the upload. That step then seeds it with one Platform Admin, as Seed data describes. No other database is migrated from a pull request, and nothing copies real data into one.

Logs and metrics. Each Preview has its own. In the dashboard, open the preview Worker and pick the Preview from its Preview selector: logs and traces are under the Preview's Observability tab, and metrics under its Metrics tab. wrangler tail doesn't support Previews.

Lifetime. Every push to the pull request redeploys its Preview, and closing the pull request, merged or not, deletes it with its Preview Database — the preview-cleanup job in .github/workflows/deploy.yml. A close that never ran or failed leaves them behind, so .github/workflows/preview-sweep.yml runs pnpm previews:cleanup --yes daily and deletes whatever belongs to a pull request that is no longer open. Cloudflare also deletes the preview Worker's least recently deployed Preview once it reaches its plan's Preview limit, 100 on Free and 500 on Paid.

Capacity. Each open pull request holds one Neon branch and one Hyperdrive configuration. Neon caps branches per project and Cloudflare caps Hyperdrive configurations per account, so a run past either Neon's branch limit or the Hyperdrive limit fails at Upsert the Cloudflare resources. Nothing waits for a slot or falls back to a shared database.

Versions. wrangler preview needs Wrangler 4.135 or later, and varlock-wrangler preview uploads the resolved environment from @varlock/cloudflare-integration 1.6 on. The catalog in pnpm-workspace.yaml pins both ranges, so keep them at or above those floors when you update.

When a deploy is skipped

The run goes green and nothing ships in these cases only, and the run log carries the reason:

  • The pull request came from another repository. GitHub withholds secrets from a fork, so an outside contributor's run cannot deploy and should not go red for it.
  • In NuxtStart, the pull request targets published. That pull request is the publication review, and nothing deploys from published, so the run builds and checks the published tree against the committed test fakes.
  • Renovate opened the pull request. A dependency update's preview shows a reviewer nothing, yet each one costs a Preview Database, an upload, and a cleanup run. An update that breaks the upload or the Worker's start fails the target branch's deploy after you merge it.
  • There are no Cloudflare credentials on the repository yet. A new project's pushes stay green this way until it adds CLOUDFLARE_API_TOKEN.

A run that cannot deploy still builds and still scans for secrets, against the committed test fakes. Your build coverage never depends on holding credentials.

A missing value never skips a deploy. Every value a deploy reads is required, so once the repository holds credentials, a Runtime Context with an empty value fails its run, and varlock's error names the key. That covers .env.project.schema, the context's value file, and its folder in the secret store alike.

Any other mistake ends the run red too, at whichever step hits it. A half-set Cloudflare secret-and-variable pair fails at the deploy with Cloudflare's own authentication error, and a Runtime Context with no committed value file fails at the build with varlock's. The one fault the gate itself reports is an unset machine-identity variable for the event, because the error it would otherwise produce names nothing.

What each application binds

Each application declares only what it uses. This is the practical difference between the two deployables.

apps/site

BindingKindSource
ASSETSStatic assets.output/public
DBD1CLOUDFLARE_D1_DATABASE_NAME and CLOUDFLARE_D1_DATABASE_ID
EMAILsend_email—

That D1 database is not an application database. It holds Nuxt Content's dump, which Content restores at runtime. The site has no Drizzle schema and no migration pipeline.

apps/web

BindingKindSource
ASSETSStatic assets.output/public
BLOBR2hub.blob → CLOUDFLARE_R2_BUCKET_NAME
POSTGRESHyperdrivehub.db → CLOUDFLARE_HYPERDRIVE_ID
EMAILsend_email—
—Cron, dailycontributed by the auth layer

R2 and Hyperdrive are configured through the hub block rather than declared directly, and the cron trigger comes from a layer — a layer contributing a binding is normal here. Where the resources on the other end come from is Resources.

The variables a deploy needs

VariablesitewebWhere it comes from
CLOUDFLARE_WORKER_NAMErequiredrequiredderived from your slug
CLOUDFLARE_WORKER_ROUTEoptionaloptionalderived from your domain, in production only
CLOUDFLARE_WORKER_ROUTE_ZONE—optionalyou
CLOUDFLARE_D1_DATABASE_NAMErequired—derived from your slug
CLOUDFLARE_D1_DATABASE_IDrequired—the deploy's resources step
CLOUDFLARE_R2_BUCKET_NAME—requiredderived from your slug
CLOUDFLARE_HYPERDRIVE_NAME—requiredderived from your slug
CLOUDFLARE_HYPERDRIVE_ID—requiredthe deploy's resources step

A required row is required in every deployed Runtime Context and in neither local nor test, so a laptop needs none of them and a deployed build that is missing one fails by name.

The names come from PROJECT_SLUG — see Project identity — and the route comes from PROJECT_DOMAIN. No file holds either id: the resources step exports each one before the build, so a full varlock load of a deployed context on your machine stops on the first by name.

Attaching a domain

CLOUDFLARE_WORKER_ROUTE is unset in every context except production, so those Workers serve from workers.dev. Production's is already built from PROJECT_DOMAIN — the site takes your domain and the product takes app. in front of it — and you change it only for a topology that rule does not cover. apps/web emits one of two forms, and NUXT_APP_BASE_URL is what selects it — a mount path other than / emits a zone-scoped route, anything else emits a Custom Domain:

ValueEmitted asAlso needs
app.example.comcustom_domain: true—
example.com/app/*a route with zone_nameNUXT_APP_BASE_URL (the switch), CLOUDFLARE_WORKER_ROUTE_ZONE
A Workers Custom Domain claims an entire hostname, so it cannot express the second shape. Setting a path-scoped pattern withoutNUXT_APP_BASE_URL emits custom_domain: true, and wrangler rejects the deploy. Nothing catches it at build time.

The second form is how you mount the product under the site's own origin instead of giving it one. apps/site only ever takes the first.

Database migrations

Only apps/web has an application database, and the pipeline applies its migrations between the build and the deploy so a Worker never serves against a schema that is behind it. The commands, when they run and what a pull request migrates are all in Database.

What a local run cannot do

Nothing local deploys. wrangler.jsonc and .wrangler/ are gitignored, so any local bindings you create stay on your machine — the deployed bindings come from the generated .output/server/wrangler.json.

Going further

Resources covers the Cloudflare resources every binding points at. Deploying development sets up development, Adding pull request previews the previews, Adding staging the optional staging, and Going to production the rest.

Copyright © 2026