Skip to main content

​
Introduction

Preview environments generate fully isolated environments for every pull request so you can test changes, share previews, and catch issues before merging. By default, each preview environment scales to zero when idle and is automatically removed when the pull request is merged or closed.
Preview environments are available on all plans, with unlimited preview environments on the Growth and Business plans. The Starter plan supports a single target environment.

​
What you can use them for

  • Review every pull request in a live environment before merging.
  • Share a live URL with team members, reviewers, and stakeholders.
  • Run automated tests and QA against isolated infrastructure.
  • Validate database migrations and infrastructure changes without impacting production.

​
How preview environments work

1

Trigger detected

Cloud listens to your linked repository and generates a preview environment when your trigger conditions are met.
2

Resources provisioned

Each preview is built from best-practice defaults: isolated, inexpensive, and scale to zero where available. You may configure our defaults to customize how each resource is provisioned.
3

Preview deployed

The preview deploys to a unique Cloud domain, which Cloud posts as a comment on the pull request.
4

Updates redeployed

New commits to the pull request rebuild and redeploy the preview.
5

Environment cleaned up

When the pull request is merged or closed, auto-destroy removes the environment and any resources it created.

​
Configuring preview environments

To create a new automation or edit an existing one:
  1. Open the environment you want to generate previews from.
  2. Navigate to Settings > Preview environments.
  3. Click New automation to create one, or select an existing automation to edit it.

​
Automation rules

Automation rules control how previews are created, deployed, and cleaned up. Each automation runs on pull requests opened against the target environment’s branch.
  • Rule name: A descriptive name for the automation.
  • Enable branch filtering: Only run when the branch name matches a specific pattern.
  • Auto-deploy on creation: Automatically deploy the new preview environment when created.
  • Delete on merge or close: Automatically delete the preview environment and its resources when the pull request is merged or closed. When disabled, previews remain until you delete them manually.

​
Replication settings

Replication settings control how each resource is provisioned for a preview environment. Defaults deliver fully isolated environments at the most economical setting, using scale to zero where available.

​
Compute

Compute covers your app compute, workers, and managed queues.
  • Create new with scale to zero (default): Isolated compute that matches your target configuration and sleeps when idle.
  • Create new with current settings: Isolated compute that matches your target configuration.
If your target environment uses Pro tier compute and you select a scale to zero option, Cloud replicates it onto the highest Flex tier with scale to zero enabled.

​
Database

  • Create new (default): An isolated database on your existing cluster.
  • Share with the target environment: Reuses your target database. Migrations and data changes affect the shared database, and data cannot be removed after a preview is deleted.
  • No database: Previews run without a database.
Sharing existing resources with preview environments introduces performance and data integrity risks and should be used with caution. A preview shares the same resource as your target environment, so its migrations or data changes can affect the target environment directly.

​
Cache

  • Create new and scale to zero (default for Valkey): Isolated cache that matches your target configuration and sleeps when idle.
  • Create new and downsize (default for Upstash): Isolated cache at the minimum available size.
  • Share with the target environment, namespaced by prefix: Reuses your cache. Entries persist after a preview is deleted and cannot be selectively removed.
  • No cache: Previews run without a cache.
Sharing a cache without a prefix is deprecated. If an existing automation still uses it, you can upgrade to a current option directly in the Cloud dashboard for improved isolation.
When you share a cache, Cloud injects a REDIS_PREFIX environment variable to isolate keys between environments. Laravel applications apply this automatically. Symfony applications must wire it into the cache configuration:

​
Object storage

  • Create new bucket (default): An isolated bucket for the preview environment.
  • Share with the target environment: Reuses your existing bucket. Files persist after a preview is deleted and cannot be selectively removed.
  • No object storage: Previews run without object storage.

​
WebSockets

  • Create new and downsize (default): Isolated WebSocket cluster at the minimum available size.
  • Create new application in an existing cluster: Adds an application to your existing cluster and shares its capacity.
  • Share with the target environment: Reuses your existing application and shares cluster capacity.
  • No WebSockets: Previews run without WebSockets.

​
Options

​
Password protection

Enable HTTP basic authentication for every preview created by the automation. Visitors enter the username admin and the password you set before traffic reaches your application. This protects preview links shared in pull requests and prevents automated bots from waking sleeping previews. Password protection is available on the Growth plan or higher.

​
Environment variables

Preview environments do not inherit environment variables from the target environment. Each automation defines its own complete set of variables. When you create an automation, Cloud prefills it with a freshly generated APP_KEY, which is shared by every preview the automation creates. This prevents production secrets from reaching preview environments. When you configure an automation, set the variables your previews need. Subject to your role’s permissions, you can view the target environment’s variables to see which keys to set, but their values are never copied automatically.
Automations created before July 1, 2026 may use a configuration that inherits environment variables from the target environment, which can carry its secrets into previews. Open the automation in the Cloud dashboard to upgrade it to the new, more secure model.

​
Injected variables

Cloud automatically injects variables into every preview, such as the credentials for its replicated resources. These variables are read-only, but you can override any of them by defining a variable with the same name in the automation’s environment variables.

​
Managing automations

​
Updating an automation

You can edit automation rules at any time. Updated rules take effect for new preview environments only. Previews already generated by the rule keep their existing configuration, so update them manually if needed. To modify an existing preview environment, edit it directly like any other environment, including resizing compute and provisioning additional resources.

​
Deleting an automation

Delete an automation from Settings > Preview environments. Deleting an automation stops new previews from being generated. Any previews it already created remain active, so delete them individually if you no longer need them.

​
Billing

Each preview environment’s resources are metered and billed like any other environment. By default, scale to zero is enabled on available resources, so previews are billed only while you’re actively previewing changes.