Skip to main content
By the end of this guide every pull request gets its own hosted copy of your app, with its own URL, its own database and an expiry date. Reviewers open the change running, and the copy is deleted when the pull request closes or its time runs out. A preview is an ordinary forge environment with an expiry marker, so env deploy and env status work on it unchanged. Preview environments is the reference for every flag.

Before you begin

  • A forge project with an environment bound to Reliant hosting, for example a prod you already deploy.
  • Forge v1.5.0 or later in the project. Check it with reliant forge --version inside the project.
  • Billing for app hosting. Each preview is a hosted environment, and each preview’s static site counts against the one free site per person (Billing).
  • Admin access to the GitHub repository, to add a secret and a workflow.
1

Create the preview template

Previews copy one committed environment, deploy/kcl/preview/ by default. Derive it from an environment you already run, then check that no REPLACE_ME_* placeholder is left:
terminal
terminal
Commit the template. From forge v1.9.0, each per-PR copy writes its own .gitignore, so nothing else is needed. On v1.8.0 and earlier, also ignore the copies, because forge writes them on every run and an untracked copy makes every preview release a dirty-tree build:
.gitignore
2

Create a preview for one pull request

Try it by hand before you automate it. The name depends only on the PR number, so the job that creates a preview and the job that deletes it agree without shared state:
terminal
terminal
--ttl takes hours or whole days and is capped at 30 days. Running create again for the same PR refreshes the copy and restarts the clock.
3

Deploy it

terminal
terminal
With no version named, env deploy builds this checkout, cuts a release named for the time and tree, and deploys it (Releases and promotion).
4

Check that the preview is live

terminal
terminal
The URL stays the same when you redeploy the preview, so a link posted on the pull request keeps working.
5

Run it from GitHub Actions

Actions has no Reliant session, so it needs an organization automation token. Give it an expiry, because cloud token create defaults to one that never expires:
terminal
Store the printed secret as the repository secret FORGE_CONTROL_PLANE_TOKEN (Deploying from CI). Then add the workflow. It deploys a preview on every push to a pull request and comments the URL, deletes it on close, and collects expired previews hourly:
.github/workflows/preview.yml
The head.repo.full_name condition keeps pull requests from forks out, because they should never get your deploy token. The runner has no Reliant CLI, so the workflow calls the npm forge binary.
6

Delete a preview when its pull request closes

This is what the down job runs. It deletes the hosted environment, its data included, then the local copy:
terminal
terminal
The URL returned 404 about 90 seconds later.
7

Collect previews that expired

On Reliant hosting the platform deletes an expired preview by itself: one deployed with --ttl 8m was gone within 15 minutes of its expiry. env gc is the backstop, and it also removes copies left in a checkout. List first, then delete:
terminal
terminal
On a cluster you operate nothing deletes previews for you, so keep the hourly gc job (Expiry and self-deletion).

What this does not do

  • No data is copied. A preview gets a new database with your migrations applied and no rows from staging or prod.
  • Secrets are not copied. Set them per preview with reliant forge env secret set --env preview-pr-<n> (Secrets).
  • CI uses a stored token. There is no OIDC or other short-lived credential path from GitHub Actions to Reliant today. Give the token an expiry, and revoke it with forge cloud token revoke.
  • It is not a dev-server link. Preview a running app shares a server running on a machine, a separate feature.

Troubleshooting

The preview’s own copy is untracked, so forge treats the tree as dirty and labels the release DIRTY TREE. Forge v1.9.0 and later ignore the copy for you; on an earlier forge, add deploy/kcl/preview-*/ to .gitignore and commit it, as in step 1.
The deploy is queued on billing, usually because the one free static site (one per person, counted across environments) is already in use by prod. It goes live once billing is set up (Queued deploys).
With no terminal, a deploy without --yes stops after cutting the release and writes no promotion. Pass --yes, or use the two-stage --plan-only / --approve form (The plan, and approving it).

Next steps

Preview environments

Every flag, naming rule and cost detail.

Deploy from GitHub Actions

Deploy staging and production from CI with an automation token.

Promote a release to production

Move the exact release staging ran to production by digest.

Releases and promotion

How releases are cut, planned and approved.