Preview Environments

Preview environments are useful for reviewing changes before production. In Hostess v1, preview deployment automation is driven outside hostess.yml: use explicit CLI targets such as hostess deploy --env preview, or use your CI provider's branch and pull request filters.

Deploy to Preview

Choose the target environment

Use the CLI to deploy to the existing preview environment:

Terminal

hostess deploy --env preview

New projects are provisioned with production and preview environments. If you target a custom environment such as staging or qa, create it first with hostess environments create staging or in Studio's Environments tab.

If you omit --env, the CLI uses the first environment returned by the API, which is usually the most recently created environment. On a standard new project that is often preview, but scripts and CI should always pass --env explicitly.

Use CI branch filters

In GitHub Actions, branch or pull request filters belong in the workflow, not in hostess.yml:

.github/workflows/preview.yml

name: Deploy Preview

on:
  pull_request:
    branches:
      - main

jobs:
  deploy-preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: howl-cloud/setup-hostess@v1
      - run: hostess deploy --env preview --no-interactive
        env:
          HOSTESS_TOKEN: ${{ secrets.HOSTESS_TOKEN }}

Keep preview state disposable when appropriate

Preview environments should use their own data and credentials. Do not restore production data into preview unless you have a deliberate test plan and have removed sensitive records.

Redis is temporary by default. Set retention: permanent only when the preview queue, session, or cache data must survive redeploys:

hostess.yml

services:
  cache:
    type: redis
    retention: ephemeral

For custom services that write to disk, omit persistence and retention: permanent unless the preview service needs durable files.

Per-Environment Secrets

Preview environments often need different secrets than production:

Terminal

hostess secrets add STRIPE_KEY --envs production --value sk_live_abc123
hostess secrets add STRIPE_KEY --envs preview --value sk_test_xyz789

This prevents preview deployments from using production credentials.

Domains

Preview environments usually use autogenerated Hostess URLs. If a long-lived preview or staging target needs a custom domain, configure only the domains field under that environment: