Setting up Preview Environments for Feature Branch Deployments

Last updated: September 19, 2025

Preview Environments allow you to automatically deploy and test feature branches before merging them into your main branch. This is particularly useful for sharing development work with teammates and stakeholders who need to review changes without setting up a local environment.

How Preview Environments Work

When enabled, Porter will automatically:

  • Create a new deployment when a pull request branch is created

  • Remove the deployment when the PR is merged or closed

Preview Environments is currently in Beta. Because of this, you may see some bugs while using it. Please report those to the Support team.

Getting Started

For detailed setup instructions and configuration options, visit our Preview Environments documentation.

Particular Use Case: Setting Dynamic URLs in Environment Variables

If you need to set preview app URLs in environment variables (such as NEXT_PUBLIC_APP_URL), you'll need to deploy twice when the PR is first created:

  1. Initial deployment: Deploy your PR branch normally to create the preview environment

  2. Get the preview URL: After the preview environment is fully deployed, run:

    porter app run -x <pr-branch> <app-name> -- env | grep PORTER_DOMAINS

    This returns a comma-separated list of domains assigned to your preview app.

  3. Set the environment variable: Use the domain from the previous step to set your environment variable:

    porter env set -x <pr-branch> -a <app-name> NEXT_PUBLIC_APP_URL=<domain-from-previous-step>

    This will redeploy your app with the new environment variable.

IMPORTANT: After this initial setup, subsequent deployments to the same PR branch will work normally with a single deployment.