---
title: "Deploy pipeline"
description: "How a push or a pull request reaches Cloudflare, and what a deploy needs from you."
canonical_url: "https://nuxtstart.com/docs/deployment/pipeline"
---

> Index of every page on this site: [llms.txt](https://nuxtstart.com/llms.txt)

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

<table>
<thead>
  <tr>
    <th>
      Event
    </th>
    
    <th>
      Runtime Context
    </th>
    
    <th>
      What runs
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Push to <code>
        development
      </code>
      
       / <code>
        staging
      </code>
    </td>
    
    <td>
      that name
    </td>
    
    <td>
      resources → build → migrate (<code>
        web
      </code>
      
       only) → <code>
        varlock-wrangler deploy
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Push to <code>
        main
      </code>
    </td>
    
    <td>
      <code>
        production
      </code>
    </td>
    
    <td>
      the same — but see below
    </td>
  </tr>
  
  <tr>
    <td>
      Pull request, whatever it targets
    </td>
    
    <td>
      <code>
        preview
      </code>
    </td>
    
    <td>
      resources and Preview Database → build → migrate it (<code>
        web
      </code>
      
       only) → <code>
        varlock-wrangler preview --name pr-<n> --json
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Pull request closed, merged or not
    </td>
    
    <td>
      —
    </td>
    
    <td>
      <code>
        wrangler preview delete --name pr-<n>
      </code>
      
       on each application's preview Worker, then delete the Preview Database
    </td>
  </tr>
  
  <tr>
    <td>
      Daily, and on demand
    </td>
    
    <td>
      —
    </td>
    
    <td>
      <code>
        pnpm previews:cleanup --yes
      </code>
      
      : delete what a closed pull request left behind
    </td>
  </tr>
</tbody>
</table>

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](https://nuxtstart.com/docs/configuration/dependency-updates#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](https://nuxtstart.com/docs/deployment/resources) covers the step.

<note>

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](https://nuxtstart.com/docs/reference/migration-publication).

</note>

## Pull request previews

A pull request does not get a Worker of its own. The workflow deploys it as a
[Cloudflare Worker Preview](https://developers.cloudflare.com/workers/previews/) 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](https://nuxtstart.com/docs/getting-started/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](https://nuxtstart.com/docs/reference/database#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](https://developers.cloudflare.com/workers/previews/#limits), 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](https://neon.com/docs/introduction/plans#branches) or
[the Hyperdrive limit](https://developers.cloudflare.com/hyperdrive/platform/limits/) 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**

<table>
<thead>
  <tr>
    <th>
      Binding
    </th>
    
    <th>
      Kind
    </th>
    
    <th>
      Source
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ASSETS
      </code>
    </td>
    
    <td>
      Static assets
    </td>
    
    <td>
      <code>
        .output/public
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DB
      </code>
    </td>
    
    <td>
      D1
    </td>
    
    <td>
      <code>
        CLOUDFLARE_D1_DATABASE_NAME
      </code>
      
       and <code>
        CLOUDFLARE_D1_DATABASE_ID
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        EMAIL
      </code>
    </td>
    
    <td>
      <code>
        send_email
      </code>
    </td>
    
    <td>
      —
    </td>
  </tr>
</tbody>
</table>

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**

<table>
<thead>
  <tr>
    <th>
      Binding
    </th>
    
    <th>
      Kind
    </th>
    
    <th>
      Source
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ASSETS
      </code>
    </td>
    
    <td>
      Static assets
    </td>
    
    <td>
      <code>
        .output/public
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        BLOB
      </code>
    </td>
    
    <td>
      R2
    </td>
    
    <td>
      <code>
        hub.blob
      </code>
      
       → <code>
        CLOUDFLARE_R2_BUCKET_NAME
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POSTGRES
      </code>
    </td>
    
    <td>
      Hyperdrive
    </td>
    
    <td>
      <code>
        hub.db
      </code>
      
       → <code>
        CLOUDFLARE_HYPERDRIVE_ID
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        EMAIL
      </code>
    </td>
    
    <td>
      <code>
        send_email
      </code>
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      —
    </td>
    
    <td>
      Cron, daily
    </td>
    
    <td>
      contributed by the auth layer
    </td>
  </tr>
</tbody>
</table>

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](https://nuxtstart.com/docs/deployment/resources).

## The variables a deploy needs

<table>
<thead>
  <tr>
    <th>
      Variable
    </th>
    
    <th>
      <code>
        site
      </code>
    </th>
    
    <th>
      <code>
        web
      </code>
    </th>
    
    <th>
      Where it comes from
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        CLOUDFLARE_WORKER_NAME
      </code>
    </td>
    
    <td>
      required
    </td>
    
    <td>
      required
    </td>
    
    <td>
      derived from your slug
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CLOUDFLARE_WORKER_ROUTE
      </code>
    </td>
    
    <td>
      optional
    </td>
    
    <td>
      optional
    </td>
    
    <td>
      derived from your domain, in production only
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CLOUDFLARE_WORKER_ROUTE_ZONE
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      optional
    </td>
    
    <td>
      you
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CLOUDFLARE_D1_DATABASE_NAME
      </code>
    </td>
    
    <td>
      required
    </td>
    
    <td>
      —
    </td>
    
    <td>
      derived from your slug
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CLOUDFLARE_D1_DATABASE_ID
      </code>
    </td>
    
    <td>
      required
    </td>
    
    <td>
      —
    </td>
    
    <td>
      the deploy's resources step
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CLOUDFLARE_R2_BUCKET_NAME
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      required
    </td>
    
    <td>
      derived from your slug
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CLOUDFLARE_HYPERDRIVE_NAME
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      required
    </td>
    
    <td>
      derived from your slug
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CLOUDFLARE_HYPERDRIVE_ID
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      required
    </td>
    
    <td>
      the deploy's resources step
    </td>
  </tr>
</tbody>
</table>

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](https://nuxtstart.com/docs/reference/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:

<table>
<thead>
  <tr>
    <th>
      Value
    </th>
    
    <th>
      Emitted as
    </th>
    
    <th>
      Also needs
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        app.example.com
      </code>
    </td>
    
    <td>
      <code>
        custom_domain: true
      </code>
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        example.com/app/*
      </code>
    </td>
    
    <td>
      a route with <code>
        zone_name
      </code>
    </td>
    
    <td>
      <code>
        NUXT_APP_BASE_URL
      </code>
      
       (the switch), <code>
        CLOUDFLARE_WORKER_ROUTE_ZONE
      </code>
    </td>
  </tr>
</tbody>
</table>

<caution>

A Workers Custom Domain claims an entire hostname, so it cannot express the second shape. Setting a
path-scoped pattern **without** `NUXT_APP_BASE_URL` emits `custom_domain: true`, and wrangler rejects
the deploy. Nothing catches it at build time.

</caution>

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](https://nuxtstart.com/docs/reference/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](https://nuxtstart.com/docs/deployment/resources) covers the Cloudflare resources every binding points at.
[Deploying development](https://nuxtstart.com/docs/getting-started/deploying-development) sets up `development`,
[Adding pull request previews](https://nuxtstart.com/docs/getting-started/adding-pull-request-previews) the previews,
[Adding staging](https://nuxtstart.com/docs/getting-started/adding-staging) the optional `staging`, and
[Going to production](https://nuxtstart.com/docs/getting-started/going-to-production) the rest.

## Sitemap

See the full [sitemap](https://nuxtstart.com/sitemap.md) for all pages.
