Skip to main content
A preview environment is a copy of one of your environments, made for a single pull request or branch, that deletes itself after a deadline you choose. Reviewers open the change running on its own URL with its own database, instead of checking out the branch, and nothing is left behind when the PR is done. Forge builds this out of parts it already has. A preview is an ordinary environment from the moment it is created, so 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 default deploy/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:
For each pull request, three commands do the work:
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).
Every push to the pull request runs 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.
A pull request from a fork gets no repository secrets, and you should not give it your deploy token. That is why the up job runs only when github.event.pull_request.head.repo.full_name == github.repository, that is, for branches in your own repository. Keep that condition if you adapt the workflow.The down job is different: deleting a preview runs nothing from the pull request, so it runs on pull_request_target, in your repository’s own context and with its secrets, for every closed pull request, a fork’s included. That deletes a fork’s preview created some other way (say, a maintainer ran create by hand) when it closes, instead of leaving it to expiry. It checks out your default branch, never the pull request’s head, so a fork’s code never runs with your token. Keep it that way: never add ref: ${{ github.event.pull_request.head.sha }}, or any step that runs the pull request’s files, to a pull_request_target 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:
Forge stamps each of those namespaces with the template it came from and its expiry, so 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:
This deletes the hosted environment, its database included, which cannot be undone, or on a cluster you operate the namespaces it renders into (only while they still carry the preview’s label). It then removes 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).