Overview

Preview environments let reviewers test changes in a production-like URL before merge. Relay builds your app on each PR, deploys to a unique subdomain, and tears down the environment when the PR closes.

jobs:
  preview:
    if: relay.event == 'pull_request'
    runs-on: relay-linux-medium
    environment:
      name: preview-${{ relay.pr.number }}
      url: https://pr-${{ relay.pr.number }}.preview.example.com
    steps:
      - uses: relay/checkout@v4
      - run: npm ci && npm run build
      - uses: relay/preview-deploy@v2
        with:
          ttl: 7d

preview:
  domain: preview.example.com
  pathPrefix: /pr

      - uses: relay/preview-comment@v1
        with:
          template: |
            **Preview ready:** ${{ steps.deploy.outputs.url }}
            Commit: ${{ relay.sha }}

Configuration options

- uses: relay/preview-deploy@v2
  with:
    ttl: 7d
    destroy-on-close: true
    destroy-on-merge: true

environment:
  name: preview-${{ relay.pr.number }}
  secrets:
    - DATABASE_URL_PREVIEW
    - STRIPE_TEST_KEY

- uses: relay/preview-services@v1
  with:
    postgres: '15'
    redis: '7'

jobs:
  preview-web:
    if: relay.changes.includes('apps/web/**')
    steps:
      - uses: relay/preview-deploy@v2
        with:
          working-directory: apps/web

Deploy gates

Require checks to pass before a preview URL is published:

Insights

Track preview usage in the Relay dashboard:

Best Practices

Performance Tip: Reuse build caches from the base branch to cut preview build times in half.

• Use path filters to skip previews for docs-only changes
• Scope secrets to preview-specific values
• Set ttl to match your review cadence (typically 3–7 days)
• Enable destroy-on-merge to avoid orphaned infrastructure