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
prodyou already deploy. - Forge v1.5.0 or later in the project. Check it with
reliant forge --versioninside 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, Commit the template. From forge v1.9.0, each per-PR copy writes its own
deploy/kcl/preview/ by default. Derive it from an environment you already run, then check that no REPLACE_ME_* placeholder is left:terminal
terminal
.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
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
5
Run it from GitHub Actions
Actions has no Reliant session, so it needs an organization automation token. Give it an expiry, because Store the printed secret as the repository secret The
cloud token create defaults to one that never expires:terminal
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
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 The URL returned
down job runs. It deletes the hosted environment, its data included, then the local copy:terminal
terminal
404 about 90 seconds later.7
Collect previews that expired
On Reliant hosting the platform deletes an expired preview by itself: one deployed with On a cluster you operate nothing deletes previews for you, so keep the hourly
--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
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
cutting new release … because the checkout has uncommitted changes (deploy/kcl/preview-pr-42/…)
cutting new release … because the checkout has uncommitted changes (deploy/kcl/preview-pr-42/…)
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.env deploy exits 7
env deploy exits 7
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).env deploy exits 5 in CI
env deploy exits 5 in CI
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.