Preview Environments

It is critical to have testing and staging environments accurately reflect production, but achieving this can be a major operational hassle. Most engineering teams use a single staging environment which makes it hard for developers to test their changes in isolation; the alternative is for devops teams to spin up new testing or staging environments manually and tear them down after testing is done.

Render's preview environments solve this problem by automatically creating a fresh copy of your production environment (including services, databases, and environment groups) on every pull request, so you can test your changes with confidence without affecting staging or relying on devops teams to create and destroy infrastructure.

Render keeps your preview environments up to date on every commit and automatically destroys them when the original pull request is merged or closed. You can also set up an expiry time to automatically clean up preview environments after a period of inactivity.

Preview environments can be helpful in a lot of cases:

• Share your changes live in code reviews: no more Git diffs for visual changes!
• Get shareable links for upcoming features and collaborate more effectively with internal and external stakeholders.
• Run CI tests against a high fidelity copy of your production environment before merging.

Getting started

1. Make sure your services and databases are defined in a render.yaml file and synchronized as a Blueprint in the Render Dashboard.

   • For details, see Render Blueprints.

2. At the root level of your render.yaml file, enable preview environments by setting the previews.generation key to one of manual or automatic:

   yaml

   previews:
     generation: automatic
   services:
   - type: web
   ...

   For details on each option, see Manual vs. automatic preview environments.

   Setting the deprecated field previewsEnabled: true is equivalent to setting this field to automatic.

3. Merge your changes to your Blueprint's linked branch.

You're all set! Open a new pull request in your repository and see your preview environment deploy with status updates right in the pull request. You can visit the URL for your preview environment by clicking View deployment next to your web service deployment.

If you'd like to try this for yourself, fork our Preview Environments example repository, synchronize the render.yaml file in your dashboard, and open a new pull request.

Manual vs. automatic preview environments

[render preview] Update homepage

Override preview instance types

Services in a preview environment can use a different instance type from their production counterparts. By using smaller instance types for preview environments, you can reduce costs.

• For Render Postgres and Key Value instances, set the previewPlan field.
• For all other service types, set the previews.plan field.

See example render.yaml declarations below. For all supported values, see the Blueprint YAML Reference.

If you don't specify a preview instance type for a service, Render uses the same instance type that you use in production.

previews:
  generation: automatic
services:
  - type: web
    plan: standard
    previews: 
      plan: starter 
    name: express-server
    runtime: node
  - type: keyvalue
    plan: standard
    previewPlan: starter 
    name: private cache
    ipAllowList: [] # only allow internal connections
databases:
  - name: my_test_db
    plan: pro-4gb
    previewPlan: basic-1gb 
    previewDiskSizeGB: 5 

Environment variables

You can override environment variables in preview environments with previewValue. This can be useful if you need to override a production API key with a test key, or if you'd like to use a single database across all preview environments. Environment variable overrides are supported for web services, private services, and environment groups.

previews:
  generation: automatic
services:
  - type: web
    plan: standard
    name: express-server
    runtime: node
    envVars:
      - key: MY_API_KEY
        value: production-api-key
        previewValue: test-api-key 

Placeholder environment variables

Placeholder environment variables defined with sync: false are not copied to preview environments. To share secret variables across preview environments:

1. Manually create an environment group in the Dashboard.
2. Add one or more environment variables.
3. Reference the environment group in your render.yaml file, as needed.

previews:
  generation: automatic
services:
  - type: web
    plan: standard
    name: express-server
    runtime: node
    envVars:
      # The value for `MY_API_KEY` provided in the Dashboard will *not* be
      # copied to preview environments.
      - key: MY_API_KEY
        sync: false

      # Any values in this group will be copied to preview environments,
      # if `all-settings` exists and is *not* included in this file.
      - fromGroup: all-settings 

Preview environment initialization

You may want to run custom initialization for your preview environment after it is created but not on subsequent deploys, for example to seed a newly created database or download files to disk. You can do this by specifying a command to run after the first successful deploy with initialDeployHook.

previews:
  generation: automatic
services:
  - type: web
    plan: standard
    name: express-server
    runtime: node
    initialDeployHook: ./seed_database.sh 

Automatic expiration

You can set the number of days a preview environment can exist without any new commits to help manage costs. Set previews.expireAfterDays to automatically delete the environment after the specified number of days of inactivity. The default is no expiry. The expiration time is reset with every push to the preview environment.

previews:
  generation: automatic
  expireAfterDays: 3 
services:
  - type: web
    plan: standard
    name: express-server
    runtime: node

Root directory and build filters

If you define the Root Directory or specify Build Filters for each service in your Blueprint Spec, Render will only create a preview environment if the files changed in a pull request match the Root Directory or Build Filter paths for at least one service.

Preview environment billing

Preview resources are billed just like regular Render services and are prorated by the second. See Render Pricing for service and instance type details.