Skip to main content

​
Introduction

Preview environments let you automatically spin up fully isolated environments for every pull request. This allows you to safely test changes, share previews with your team, and catch issues before merging, all without impacting your production environments. Each application in your organization can have its own automation rules and preview workflows.
Preview environments are available for Growth and Business plan customers.

​
How preview environments work

When you configure a preview environment automation on your app:
  1. Laravel Cloud listens for pull requests or new branch events on your linked repository.
  2. When triggered, a new preview environment is created.
  3. The environment is based on a specified existing environment (e.g. dev), including compute, resources, and environment variables.
  4. The environment receives a unique Cloud domain that can be used to preview changes or share with coworkers and clients.
  5. If the automation is triggered via pull request:
  6. Cloud will add a comment to the PR with a link to the environment.
  7. By default, Cloud deploys the environment automatically and updates the PR comment with a link to the new environment’s Cloud domain when the deployment finishes.
  8. The preview environment lives independently until the branch is deleted or pull request is closed. If auto-destroy is enabled, the environment and any resources that were created will be automatically removed; otherwise, manual cleanup is required.

​
Best practices

  • If you have a dev or staging environment, replicate that environment so preview environments share its configuration and resources. Otherwise, create a template environment specifically for preview environments.
  • Use the template environment to customize any preview environment specific settings.
  • Use feature flags or environment variables to control preview-only behavior.
  • Use seeded test data rather than copying production data.
Preview environments reuse the APP_KEY from the replicated environment. Avoid connecting preview environments to production databases, caches, or other sensitive resources. We don’t recommend replicating a production environment for previews. If you share resources across environments, be aware that running migrations, making breaking changes, or altering data can impact other environments.

​
Configuring preview environments

To configure a preview environment automation:
  1. Go to your Laravel Cloud organization.
  2. Select an environment in the app you want to configure.
  3. Navigate to Settings > Preview environments under Application settings.
  4. Click Get started or + New automation to create a new preview environment automation.

​
Automation settings

  • Automation name: Enter a descriptive name for your automation.
  • Environment to replicate: Select which existing environment (e.g. dev) to use as a template. This environment’s configuration (compute, resources, environment variables, etc.) will be used for each preview environment. Use a development or staging environment as the template to keep production data safe.
  • Automation triggers on:
    • New pull requests: Automatically create a preview environment when a pull request is opened against a target branch.
    • New branches: Automatically create a preview environment when a new branch is pushed.
  • Target branch: If using pull request triggers, select which branch to listen for pull requests against (e.g. dev).
  • Filter by branch name (optional): Only run automation if the branch name matches a specific pattern.

​
Replication options

Choose which resources to duplicate, reuse, or ignore for preview environments:
  • Compute clusters: Replicate the compute settings from the template environment, replicate and downsize, or reset to Cloud’s default compute settings.
  • Database: Optionally attach a database instance.
  • Cache: Optionally attach a cache resource.
  • Object storage: Optionally attach object storage.
  • WebSockets: Optionally attach a WebSocket application.
  • Custom environment variables: Specify variables to override or add for preview environments.

​
Deployment options

  • Auto deploy on trigger: Enable to automatically deploy the preview environment upon creation. When disabled, environments are created but require manual deployment.
  • Auto destroy environment and resources: Enable to automatically destroy the preview environment and its resources when the pull request is merged or closed. When disabled, environments must be manually deleted.
  • Initial deploy commands: Optionally specify shell commands to run after the first deploy (e.g. php artisan db:seed --force). These commands are useful for setting up preview-specific data.

​
Managing preview environments

  • Active preview environments appear in the application selector or the Recently deployed section on your org overview.
  • Preview environments are named after the pull request or branch.
  • When you push new commits to a pull request, the associated preview environment will automatically rebuild and redeploy.