> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a preview environment for every pull request

> Give each pull request its own hosted copy of your app on its own URL, created and deleted from GitHub Actions, and cleaned up by itself when it expires.

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](https://docs.reliantlabs.io/hosting/preview-environments.md) is the reference for every flag.

## Before you begin

* A forge project with an environment bound to [Reliant hosting](https://docs.reliantlabs.io/hosting/overview.md), 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](https://docs.reliantlabs.io/hosting/overview.md#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:

```bash terminal theme={null}
reliant forge env new preview --from prod
reliant forge env new preview --check
```

```text terminal theme={null}
Scaffolded environment "preview" from "prod":
  deploy/kcl/preview/main.k
✓ env "preview": no placeholders remaining and KCL compiles.
```

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:

```text .gitignore theme={null}
deploy/kcl/preview-*/
```

**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:

```bash terminal theme={null}
reliant forge env preview create --pr 42 --ttl 72h
```

```text terminal theme={null}
Created preview preview-pr-42 (from preview, pr-42), expires 2026-11-23T08:22:04Z
  deploy/kcl/preview-pr-42

Next: reliant forge env deploy preview-pr-42 --yes
```

`--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**

```bash terminal theme={null}
reliant forge env deploy preview-pr-42 --yes
```

```text terminal theme={null}
[deploy] cutting new release 20261120.082841-268a7fcc4c9c because no release in https://admin.reliantapi.com records this checkout's tree (268a7fcc4c9c)
  environment preview-pr-42 exists (id b6e497b6-ff10-4d04-a58f-4d8ede1493b2)
  url web: https://easy-cougar.sites.reliantlabs.dev (served through the CDN edge)
Rollout of 20261120.082841-268a7fcc4c9c to preview-pr-42: SUCCEEDED
```

With no version named, `env deploy` builds this checkout, cuts a release named for the time and tree, and deploys it ([Releases and promotion](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md)).

**4. Check that the preview is live**

```bash terminal theme={null}
curl -s -o /dev/null -w '%{http_code}\n' https://easy-cougar.sites.reliantlabs.dev/
reliant forge env status preview-pr-42 --json | jq -r '[.. | .url? // empty] | unique | join("\n")'
reliant forge env list
```

```text terminal theme={null}
200
https://easy-cougar.sites.reliantlabs.dev
dev
preview
preview-pr-42
prod
staging
```

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:

```bash terminal theme={null}
reliant forge cloud token create --env prod --name github-previews \
  --scopes deploy:read,deploy:write --expires-in 720h
```

Store the printed secret as the repository secret `FORGE_CONTROL_PLANE_TOKEN` ([Deploying from CI](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md#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:

```yaml .github/workflows/preview.yml theme={null}
name: preview
on:
  pull_request:
    types: [opened, synchronize, reopened, closed]
  schedule:
    - cron: "17 * * * *"          # hourly: delete expired previews
concurrency:
  group: preview-${{ github.event.pull_request.number || 'gc' }}
  cancel-in-progress: false
permissions:
  contents: read
  pull-requests: write
jobs:
  up:
    if: >-
      github.event_name == 'pull_request' &&
      github.event.action != 'closed' &&
      github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    env:
      FORGE_CONTROL_PLANE_TOKEN: ${{ secrets.FORGE_CONTROL_PLANE_TOKEN }}
      PR: ${{ github.event.pull_request.number }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm i -g @reliantlabs/forge
      - id: preview
        run: |
          forge env preview create --pr "$PR" --ttl 72h --json > preview.json
          echo "name=$(jq -r .name preview.json)" >> "$GITHUB_OUTPUT"
      - run: forge env deploy "${{ steps.preview.outputs.name }}" --yes
      - name: Comment the URL
        env:
          GH_TOKEN: ${{ github.token }}
          NAME: ${{ steps.preview.outputs.name }}
        run: |
          urls=$(forge env status "$NAME" --json | jq -r '[.. | .url? // empty] | unique | join("\n")')
          gh pr comment "$PR" --edit-last --create-if-none \
            --body "Preview \`$NAME\` (expires $(jq -r .expires_at preview.json)):
          ${urls}"
  down:
    if: >-
      github.event_name == 'pull_request' &&
      github.event.action == 'closed' &&
      github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    env:
      FORGE_CONTROL_PLANE_TOKEN: ${{ secrets.FORGE_CONTROL_PLANE_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - run: npm i -g @reliantlabs/forge
      - run: forge env preview delete --pr ${{ github.event.pull_request.number }} --yes
  gc:
    if: github.event_name == 'schedule'
    runs-on: ubuntu-latest
    env:
      FORGE_CONTROL_PLANE_TOKEN: ${{ secrets.FORGE_CONTROL_PLANE_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - run: npm i -g @reliantlabs/forge
      - run: forge env gc --yes
```

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:

```bash terminal theme={null}
reliant forge env preview delete --pr 42 --yes
```

```text terminal theme={null}
Removed: the environment, its deployments, workloads, URLs, Flux objects, custom resources, namespaces
  AND its managed databases' data. IRREVERSIBLE (pass --keep-data to retain the databases).
Kept: the project's release images in the registry (they belong to the project, not this environment).

Deleted env preview-pr-42; the platform is tearing it down, its databases included.
[preview] deleted preview-pr-42
```

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:

```bash terminal theme={null}
reliant forge env gc --dry-run
reliant forge env gc --yes
```

```text terminal theme={null}
would delete instance preview-gc-demo (preview of preview, expired 2026-11-20T08:40:23Z)
[preview] deleted preview-gc-demo
deleted instance preview-gc-demo (preview of preview, expired 2026-11-20T08:40:23Z)
```

On a cluster you operate nothing deletes previews for you, so keep the hourly `gc` job ([Expiry and self-deletion](https://docs.reliantlabs.io/hosting/preview-environments.md#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](https://docs.reliantlabs.io/hosting/secrets.md)).
* **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](https://docs.reliantlabs.io/cli/previews.md) shares a server running on a machine, a separate feature.

## Troubleshooting

> [accordion] 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.

> [accordion] 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](https://docs.reliantlabs.io/hosting/overview.md#queued-deploys)).

> [accordion] 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](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md#the-plan-and-approving-it)).

## Next steps

> [card] [Preview environments](https://docs.reliantlabs.io/hosting/preview-environments.md)
>
> Every flag, naming rule and cost detail.

> [card] [Deploy from GitHub Actions](https://docs.reliantlabs.io/guides/hosting/deploy-from-github-actions.md)
>
> Deploy staging and production from CI with an automation token.

> [card] [Promote a release to production](https://docs.reliantlabs.io/guides/hosting/promote-release-staging-to-production.md)
>
> Move the exact release staging ran to production by digest.

> [card] [Releases and promotion](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md)
>
> How releases are cut, planned and approved.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.