forge env deploy, forge env status and forge obs check work on it unchanged. What makes it a preview is a marker that says which environment it copies and when it expires.
This is not the same as Preview a running app. That page covers
reliant preview-url, the browser URL of a dev server listening on a machine, which exists only while the server runs. A preview environment is a deployed copy of your project, with its own hosted workloads and database, that lives until it expires or you delete it.How it works
You commit one template environment, by defaultdeploy/kcl/preview/, that describes what a preview should be. Derive it from an environment you already run, then fill in the placeholders forge leaves for per-environment values:
create copies the template’s files verbatim into deploy/kcl/preview-pr-123/ and marks the copy with its expiry. deploy then builds and promotes it like any other environment, with its own release record. When the deploy finishes, its result line prints the environment’s URL, and reliant forge env status preview-pr-123 shows it again later.
The instance directory is a throwaway. Edit the template, never the copy, because the next create overwrites it, and do not commit instances: a CI checkout makes them fresh each time.
From forge v1.9.0, create also writes a .gitignore inside the instance directory that ignores all of it, so creating a preview leaves the checkout clean and its release is not a dirty-tree build. On v1.8.0 and earlier, add deploy/kcl/preview-*/ to the project’s .gitignore yourself. Without it, the untracked copy makes forge cut every preview release as DIRTY TREE.
Names
The name depends only on the pull request or branch, so the job that creates a preview when a PR opens and the job that deletes it when the PR closes agree without sharing any state.--pr 123 gives preview-pr-123. --branch feat/Login_Page gives preview-feat-login-page. reliant forge env preview name --pr 123 prints the name without creating anything, and --name-template changes the shape ({env} is the template’s name, {id} is pr-<n> or the branch). A name is at most 40 bytes: a longer one is cut and given a short hash suffix so two long branch names never collide.
Commands and flags
create refuses three things: a template that is itself a preview, an existing directory of that name that is not a preview of the same template, and an instance that would render into a Kubernetes namespace the template environment also renders into.
Create one per pull request from CI
Save this as.github/workflows/preview.yml. It is yours, and forge does not generate it. It needs the same credential as your deploy workflow: an organization automation token stored as the FORGE_CONTROL_PLANE_TOKEN secret (see Deploying from CI).
create again, which refreshes the copy and moves the expiry to a fresh 72 hours, and deploy then ships the new commit to the same environment. The down job deletes the preview when the PR closes. The gc job is the backstop for a PR whose close event never ran the job.
The runner installs the standalone forge CLI from npm, so the workflow calls forge, not reliant forge.
The same three commands work from anywhere that has a checkout of the project and a credential. A Reliant workflow can run them from a run node, and on a Reliant machine forge uses your signed-in session instead of a token (Forge sign-in).
What a hosted preview gets
When the template binds its workloads to Reliant hosting (forge.OnHosted), nothing else needs configuring. Each instance becomes its own hosted environment with its own generated URL, its own managed Postgres database and its own secrets.
The database is created for that environment and the deploy runs your migrations against it, so a preview starts with your schema and no data. Forge copies the template’s configuration, not anything from a running environment: no rows come over from staging or prod.
Secrets are per environment and are not copied from the template. Give each instance the secrets it needs with reliant forge env secret set --env preview-pr-123 <NAME> (see Secrets), or keep previews on configuration that needs none.
If the template renders onto a Kubernetes cluster you operate instead, give each preview its own namespace by deriving it from the environment name, which forge sets on every render:
reliant forge env gc finds expired previews from the cluster alone, even when the CI runner that made them is gone. Pass --context <kubectl-context> to gc to scan a cluster the template does not render into.
Expiry and self-deletion
--ttl sets how long a preview lives. It is a duration (72h) or whole days (7d), defaults to 72 hours, and can be at most 30 days. The expiry is recorded in the environment’s declared shape on every deploy.
On Reliant hosting, the platform deletes an expired preview for you. It checks every five minutes and deletes the hosted environment, its workloads and its database, the same as forge env delete would. There is no confirmation and no --keep-data: a preview’s data is throwaway by declaration. A preview whose expiry cannot be read is never deleted, and one that you refresh with create and redeploy before the deadline keeps living.
A hosted preview with a custom domain bound to it is not deleted until you unbind the domain (Custom domains).
On a cluster you operate, nothing deletes it for you. Run reliant forge env gc --yes on a schedule, as the gc job above does.
Delete one early
When a PR closes, or you simply want the environment gone:deploy/kcl/preview-pr-123/. In a fresh CI checkout where that directory is gone, forge re-creates it from the template first to learn what to delete. reliant forge env gc --dry-run shows which previews have already expired.
What it costs
A preview is a real hosted environment, so it is billed like one. Workloads and managed databases need the organization’s pay-as-you-go app hosting billing, and CPU, memory and storage are billed from first use for as long as the preview exists. If billing is not active,forge env deploy queues the deploy and exits with code 7 rather than failing, and the preview goes live once someone sets billing up (Queued deploys).
A frontend-only template falls under the static site free tier, which allows one static site per person, across the organizations they own without a plan, counted across all environments. Each preview’s site counts, so with your prod site already live, the first preview is queued like any other billing hold. Traffic is shared too: the 10 GiB per month is for the whole organization. Details are on Hosting on Reliant.
Cost therefore follows how many previews exist at once and for how long. A short --ttl, the delete on PR close, and an hourly gc keep it down. reliant forge env stop <env> suspends a preview’s workloads without deleting it (Stopping and deleting an environment).
Related topics
- Hosting on Reliant: what hosting runs, billing, queued deploys
- Environments: template environments,
forge env newand bindings - Releases and promotion:
forge env deploy, exit codes and deploying from CI - Secrets: per-environment secrets for a preview
- Custom domains
- Preview a running app: the dev-server URL on a machine, a different feature