Environments & previews
A vertical you own has exactly one channel — prod (the deploy model). There is no dev, no staging. That is not a missing feature; it is the point. On most platforms an environment is a second deployment — another machine running other code. Substrat inverted both halves: code is shared and nearly free (one hibernating Durable Object class per version), and the isolation boundary is the scope. So the thing that separates one environment from another here is which scope, not which deployment — and a scope with its own data already has a name and a URL. A second pointer at the same code would add nothing.
So a non-production environment on Substrat is a preview: a scope with data, bound to a version, reachable at its own hostname. This page is how you use that one primitive to get every workflow the old three-environment ladder gave you — and a few it couldn't.
The mental model: an instance is (scope × version)
Three primitives, and the whole page falls out of how they compose (preview & snapshots RFC §2):
| Primitive | Mutability | Git analogy |
|---|---|---|
version id → a deploymentRef | immutable — a pushed build never changes | a commit sha |
binding (bindScopeVersion) — the scope’s selected version | mutable by design | a branch ref |
| hostname → resolves to a scope | stable; names a scope, never a version | a checkout path |
A running app is a scope bound to a version, fronted by a hostname. The router resolves hostname → scope, then uses its production serving pin when present, otherwise its bound version’s deployment. New previews have no serving pin; older previews may still have one, as described in the existing-pin warning below. The binding alone is not proof of running code.
This is why prod is already a moving target: the prod hostname points at the prod scope, and a promote rebinds that scope to a new version. "test" and "prod" are the same shape — a stable scope + a stable hostname whose binding moves. The only thing that differs is what triggers the rebind, and how gated it is:
- prod — the binding moves on an explicit, acknowledged promote; across a shared vertical's tenants it cascades.
- test — the binding moves through an explicit preview push or scope bind. CI can run that step on every merge to
main; production promotion does not do it.
Previews: the non-prod primitive
A preview is a scope with data bound to a version, at its own --<tag> hostname. You create and manage them with substrat preview:
substrat preview create . --tag pr-42 # push this tree, fork prod, serve the pair
# ✓ preview 'pr-42' → https://helpdesk-acme--pr-42.global.substrat.run
substrat preview ls
substrat preview delete --tag pr-42 # reap it (idempotent)create pushes the working tree (so the bound version is exactly this code), forks the vertical's prod scope, binds the pushed version to the fork, and mints a non-canonical --<tag> hostname. Two properties do the heavy lifting:
- A preview is idempotent per tag. Re-running the same
--tag— what a new push to a PR does — rebinds the new version onto the same fork, and moves the fork's data with it. Successive pushes roll their migrations forward on the same data, which is the rehearsal that actually de-risks a release: the fork accumulates schema changes exactly the way prod will.--refreshstarts over from a clean fork of prod. While a create for a tag is still forking, a second create for that tag answers 409 rather than wiping it. If the first create failed, the retry normally forks again at once. If it died without reporting back (or could not record its own failure), the tag frees itself 15 minutes after that create started.--refreshreplaces it sooner, and stops a create still running. - A prerelease label never steals a release coordinate. A default preview push is labelled
<pkg>-<tag>.<n>(a semver prerelease), and the registry'snextVersiononly counts anchoredx.y.zreleases — so preview pushes are free: they never collide with, and never advance, the version your repo owns. (Pass--versionto pin an exact label.)
Moving between deployments copies data; writes during the copy can be lost
On a host with a per-version resolver, a push that moves an existing preview between distinct version deployments first copies its data, then switches the URL over. No copy is needed when routing stays on the same script or the incoming version is co-located. When a copy occurs:
Anything written to the preview while the push runs may be lost. The copy is taken before the switch, so a change made in between stays behind on the previous version.
preview createprints aData:line whenever it moved data, as a reminder.Each carry copies the whole preview. A preview holding a lot of data makes that push slower. A copy too large for one request runs in the background:
preview createprints how far it has got and waits, and the preview keeps serving the previous version until the copy is done. A newer push to the same preview stops an older one that is still copying, and takes over. A create for an older version is refused while a newer push's copy is running or being finished, and for 15 minutes after that push's last call; after that, an older version can be previewed again.Concurrent creates of the same version share one staged copy. If both reach the destination before a copy job is visible, the second gets a retryable
503while the first page is staged. The CLI retries, then receives the usual202progress answer once the first job exists and polls it. If the short retry window ends first, runpreview createagain after the copy. Failed, cancelled and superseded jobs discard their own stages. If a job record disappears entirely, its stage is reclaimable after the six-hour job limit plus the lease safety margin.A copy needs its source to hold still. It reads the source in pages, so a source that takes a write between two pages is copied again from the start. One that keeps changing through three attempts is refused (
409) with nothing moved; re-run the push when it is quieter.A failed copy changes nothing. The preview stays on the previous version with its data, and re-running the push tries again. A background copy that fails ends
preview createwith the reason; it is never started over without a new push.The previous version's copy is wiped once the switch lands. It is emptied rather than deleted, so binding the preview back to that version later copies the data into it again.
Two pushes to the same preview at once cannot both switch it. When a retried CI job runs next to a new push, the one that finishes second is refused (
412), its copy is discarded, and re-running it moves the data from wherever the first one left the preview. A push that has fallen behind never copies over the version the preview is already being served from.
If a write reaches the previous version's copy while the push runs (a request that was already on its way there), that copy is kept instead of wiped, because it holds something the new version does not. A later bind back to that version is then refused until platform staff resolve the kept copy. They either discard it, or restore it forward over the live preview, which replaces what the preview took since.
The wipe is best effort. A push that fails after it copied the data, but before the switch or the wipe completes, can still leave a copy behind. Those copies, and the ones left in earlier versions by pushes made before the wipe existed, are not removed yet (#1722).
Every preview carries a TTL (--ttl 72h by default) so an abandoned one is garbage-collected even if never deleted — and reuse renews the deadline, so an actively-pushed preview never dies under you. --ttl none pins it until you delete it (see the test environment below).
Previews are for a vertical you own
A preview forks your own tenant's scope and serves no install, so a builder may preview a vertical they own whether it is private or listed — publishing widens who may install, not who may preview their own pending code (#513). What a preview will not do is fork a scope pinned tighter than global-jurisdiction, or fork a first-party vertical you don't own.
What a fork carries over, and what it doesn't
A fork copies the app's data. A setting from the dashboard's Env tab also carries to the preview when both the source and preview versions declare it non-secret with previewCarry: true. The platform delivers those opted-in values on every push. Other settings are not copied and use the preview deployment's defaults. The preview's database data is retained across pushes. The per-install Identity choice (substrat:auth) is handled separately, as described below.
Deleting a preview clears the settings delivered into its current deployment; settings delivered into an earlier deployment can remain in that deployment's tenant store after a later push and reap.
The login is handled for you when the app signs in at one of your team's auth servers. Each create and each push registers a client of the preview's own at that auth server, delivers it to the preview, and removes the one the previous push used. Deleting the preview, or letting it expire, removes it too. Your app's own client is never changed, and it never learns a preview's address.
The same auth server is also told to mint tokens for the preview's MCP endpoint, https://<app>--<tag>.<base>/api/mcp, so an MCP client pointed at the preview gets a login page instead of invalid_target. A token for the preview's endpoint is refused by your app's own endpoint, and the reverse. Deleting the preview (by preview delete, or retiring it from the console or the dashboard) or letting it expire un-registers the endpoint, and your app's registration is never touched. If the registration fails, the preview's login still works: preview create says so, and the next push registers it again.
Any other login isn't copied. For an external issuer (Auth0, Keycloak, Supabase, …), preview create tells you so and prints the preview's callback, https://<app>--<tag>.<base>/api/auth/callback. The dashboard shows the same callback on the preview's row. Registering it at the issuer isn't enough on its own: the platform never copies your app's client secret to a preview.
For a fork, preview create includes this settings line:
Settings: only non-secret Env tab settings explicitly declared for preview carryover are delivered; other settings use the deployment's defaults.A vertical's first environment — the clean room
A fork needs something to fork. A brand-new vertical has no prod scope yet — exactly when a throwaway environment is most useful. --empty provisions a clean-room scope instead of forking: module tables migrated, version bound, hostname minted, no data.
substrat preview create . --tag sandbox --empty # a source-less environmentIt follows the tenant-app hostname convention (<vertical>-<tenant>--<tag>.<base>) since there is no source URL to derive from. This is the "empty / seed data → clean-room preview" cell of the model — a first environment before any prod exists (#514).
Production promotion and bulk serving adoption exclude every preview, including clean-room test environments with no expiry. Explicit adopt-serving on a preview returns 409. Advance a preview with an explicit preview push or scope bind; its tag and TTL do not enable production auto-follow. A test environment created through the dashboard starts empty at the production version, or the first admitted version if none is in production. The dashboard also displays existing tagged previews, which may contain copied data. It shows the bound version, not a verification of the code serving the URL.
Existing production serving pins need a bind or push
A preview adopted before this prevention change may still carry a servingRef and serve production code even while its bound version stays unchanged. A directory version or dashboard label alone cannot prove what that URL runs. A preview push or scope bind now carries the preview's data from the serving script to the bound version's script before clearing the pin. Binding the currently bound version is enough to repair a long-lived preview without advancing it. Previews that are never pushed or bound are repaired by a one-time platform pass that does the same thing for each (#1724): it carries the data, binds the version the preview already has, and only then clears the pin, so a preview that fails is left pinned with its data and retried on the next run. Once a preview's pin is cleared, its copy on the serving script is wiped. Do not clear a pin without carrying its data.
Sticky-per-PR and per-build URLs
Because a hostname names a scope, and the router serves that scope's current binding, two URLs on one scope cannot resolve to two different versions. That single fact dictates the shape of good PR previews — and it is exactly git's branch-vs-sha discipline:
| URL | Backed by | Behaviour |
|---|---|---|
Sticky PR URL — …--pr-42.<base> | one long-lived fork, rebound every push | always the latest push on the PR; bookmark it once. The branch ref. |
Per-build URL — …--pr-42-<run>.<base> | a fresh scope per build, never rebound | frozen to exactly that build, forever. The sha. |
The sticky URL is what a reviewer watches; the per-build URL is what you paste into a comment when a regression appears in one specific build and must stay that build. The moving pointer is only safe because every build is also addressable immutably — you can always de-reference "the bug on the PR preview" down to a fixed artifact.
The recipe is two preview create calls per push:
substrat preview create . --tag pr-$PR # sticky: reused, renews its TTL
substrat preview create . --tag pr-$PR-$RUN --empty --ttl 24h # per-build: fresh, short-livedYou do not have to write that yourself — substrat init --ci github and the dashboard's one-click CI setup generate the same workflow, which creates the sticky preview on every PR push and comments the URL back. The per-build call is opt-in, because a frozen scope per build is a real cost: set the repository variable SUBSTRAT_PER_BUILD_PREVIEW to 1 and the same workflow adds it, with the PR comment then naming both URLs — the one that follows the PR and the one frozen to this build.
The per-build preview is deliberately --empty rather than a fork: it is thrown away within a day, so copying prod data into it on every push would be pure cost. If you need a frozen copy with data, that is a snapshot of the sticky preview, not a per-build one.
A long-lived test environment
A "test environment that always runs the latest main" is just a pinned preview whose binding is rebound on every merge, fronted by a custom domain. Nothing new — three primitives you already have:
A durable scope. Create it pinned so the GC sweep never reaps it:
bashsubstrat preview create . --tag test --ttl none # forks prod; or --empty for a fresh oneA custom domain on it. A hostname binds to any scope you own, not just prod — attach one with
substrat scope domain:bashsubstrat scope domain <testScopeId> --domain crm-test.ahero.se # → verifying — publish the CNAME/TXT it prints; live when activeThe scope is now protected from reaping while that domain resolves, exactly like a prod scope (the reap guard counts any bound hostname).
A rebind on every merge. In the merge-to-
mainjob, after the build, pin the test scope to the version you just pushed:bashsubstrat scope bind <testScopeId> --version <justPushedId> --snapshotThe bind moves the test scope's data into the version it binds, the same way a push to a preview does, with the same caveat: a write made to the test environment while the bind runs may be lost.
For a preview without an existing production serving pin, each successful merge-job bind makes crm-test.ahero.se serve that pushed version; migrations roll forward on its accumulated data, rehearsing every prod migration a merge earlier; and prod stays behind its gated promote. All of it is manageable from the dashboard too — pin a preview, attach a domain, and (per app) bind a version — no CLI required.
Why "tracks main" stays a CI step, not a platform setting
Substrat enables this workflow; it deliberately does not encode it. A "this scope auto-tracks tag X" toggle would be a new environment noun — the same temptation the retired dev/staging channels gave in to, re-buried one layer down. A one-line scope bind in your merge job is more legible and composes with any branching model. Revisit only if you have many test slots wanting a shared rule.
Canary & pinned tenants — per-scope rollout
The same scope bind primitive is the whole rollout axis for a shared vertical with many tenant scopes. A prod promote cascades every tenant to the new version; when you want tenant A first, bind that one scope ahead:
substrat scope bind <tenantA-scopeId> --version <next> --snapshot # canary one tenant
# … watch it, then promote prod to bring the rest along--snapshot forks the scope's data before a migration-crossing bind, so a bad version leaves the prior one still runnable at its correct migration frontier — fork-before-you-promote, applied per scope. A binding drift is native and expected: an install pins "prod-at-the-time", and Update to latest is the per-scope catch-up. The channel was always the weaker abstraction here — it can't express "tenant A first"; the binding can.
The release workflow: pnpm + changesets
The version your repo owns lives in package.json, not in a registry counter — so a merge does not move it, and only a release does. This is the workflow the generated CI encodes, and it maps cleanly onto the primitives above:
| Moment | Version label | What runs | Where |
|---|---|---|---|
| PR opened / pushed | <next>-pr-<n>.<k> | preview create --tag pr-<n> | sticky …--pr-<n>, a fork of prod |
Merge to main (changeset lands; version does not move) | <pkg>-test.<run> | push, then scope bind <testScope> | crm-test.ahero.se, the long-lived test env |
| Version PR ("chore(release): version packages") | <next>-pr-<n>.<k> | nothing special — it is a PR, so it gets a PR preview | that preview is the release candidate: the code that is about to become prod, on a fork of prod data, while rejecting it is still free |
| Version PR merges (version moves) | <pkg> exactly | push --version <pkg>, then a tip-guarded promote — skipped if main already declares a newer version, so a queue that resumes out of order can never point prod at older code | prod |
Note what row 3 does not need: a release-candidate channel, an rc tag, or any new noun. A version PR is a pull request, so the ordinary PR preview already runs the release candidate against forked prod data. The one thing that differs between it and the prod push is the version label — the code is the same tree.
Two disciplines make this safe, and both are already true — this workflow just names them:
- A non-release push never claims a release coordinate, because prerelease labels are skipped when the registry computes the next version. PR previews, the test env, and the release candidate all push freely without punching holes in your version sequence.
- The release candidate is the one moment the exact artifact that will become prod runs against a fork of prod's data while the change is still a PR — i.e. while rejecting it costs nothing. It is also where the
--ack-permissions/--ack-migrationsacknowledgements are earned rather than typed at the same instant as the deploy.
Don't hand-roll it
Generate it:
substrat init --ci github --release changesetssubstrat init and the dashboard's one-click CI setup render the same workflow from the same generator — merge-to-main release, the test-env rebind, and the PR previews with their comment. The label discipline and the two-preview-per-push recipe are not something you should have to re-derive per vertical, and the reason this command exists is that the first workflow we shipped got the label part wrong: it pushed --version 0.1.<run number> on every run, claiming a real registry coordinate each time and punching holes in the version sequence.
See also
- Deploying a vertical — push, admission, promote prod, serve-in-place.
- The deploy model — the concepts behind the one channel and in-place serving.
- Snapshots & test copies — the data-fork machinery a preview is built on.
@substrat-run/cli—preview,scope bind,scope domain,promote.