Deploy pipeline
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
| Event | Runtime Context | What runs |
|---|---|---|
Push to development / staging | that name | resources → build → migrate (web only) → varlock-wrangler deploy |
Push to main | production | the same — but see below |
| Pull request, whatever it targets | preview | resources 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.
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 frompublished, 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
| Binding | Kind | Source |
|---|---|---|
ASSETS | Static assets | .output/public |
DB | D1 | CLOUDFLARE_D1_DATABASE_NAME and CLOUDFLARE_D1_DATABASE_ID |
EMAIL | send_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
| Binding | Kind | Source |
|---|---|---|
ASSETS | Static assets | .output/public |
BLOB | R2 | hub.blob → CLOUDFLARE_R2_BUCKET_NAME |
POSTGRES | Hyperdrive | hub.db → CLOUDFLARE_HYPERDRIVE_ID |
EMAIL | send_email | — |
| — | Cron, daily | contributed 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
| Variable | site | web | Where it comes from |
|---|---|---|---|
CLOUDFLARE_WORKER_NAME | required | required | derived from your slug |
CLOUDFLARE_WORKER_ROUTE | optional | optional | derived from your domain, in production only |
CLOUDFLARE_WORKER_ROUTE_ZONE | — | optional | you |
CLOUDFLARE_D1_DATABASE_NAME | required | — | derived from your slug |
CLOUDFLARE_D1_DATABASE_ID | required | — | the deploy's resources step |
CLOUDFLARE_R2_BUCKET_NAME | — | required | derived from your slug |
CLOUDFLARE_HYPERDRIVE_NAME | — | required | derived from your slug |
CLOUDFLARE_HYPERDRIVE_ID | — | required | the 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:
| Value | Emitted as | Also needs |
|---|---|---|
app.example.com | custom_domain: true | — |
example.com/app/* | a route with zone_name | NUXT_APP_BASE_URL (the switch), CLOUDFLARE_WORKER_ROUTE_ZONE |
NUXT_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.
