Creating preview environments with PR Generator is about giving developers ephemeral, production-like sandboxes for every pull request.
Here’s a typical workflow:
- Developer opens a PR: A new branch is pushed to your Git repository.
- CI/CD pipeline triggers: This pipeline is configured to detect new PRs.
- PR Generator spins up a preview environment: This involves provisioning resources (like containers, VMs, or serverless functions) and deploying the application code from the PR branch.
- Environment is made accessible: A unique URL is generated, often accessible only to authorized users or team members.
- Testing and feedback: Developers and QA can test the changes in this isolated environment.
- PR is merged or closed: The preview environment is automatically torn down, cleaning up resources.
Let’s see this in action. Imagine you’re using GitHub Actions and a service like Vercel for deployments.
Your GitHub Actions workflow (.github/workflows/preview.yml) might look like this:
name: Preview Environment
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
build-and-deploy-preview:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
- name: Install dependencies
run: npm ci
- name: Build application
run: npm run build
env:
CI: true
- name: Deploy to Vercel Preview
uses: amondnet/vercel-action@v2
with:
vercel-token: ${{ secrets.VERCEL_TOKEN }}
github-token: ${{ secrets.GITHUB_TOKEN }}
project-name: your-project-name # Replace with your Vercel project name
# Add any environment variables needed for deployment
# env: |
# NEXT_PUBLIC_API_URL=https://api.staging.example.com
env:
VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
When a PR is opened or updated, this workflow checks out the code, installs dependencies, builds the app, and then uses the amondnet/vercel-action to deploy it to a Vercel preview environment. Vercel automatically generates a unique URL (e.g., your-project-name-git-pr-123-your-org.vercel.app) and comments it on the PR.
The problem this solves is the "it works on my machine" syndrome and the friction of manual deployments for every small change. Instead of merging to a shared develop or staging branch and hoping for the best, each PR gets its own isolated, production-like deployment. This allows for thorough testing without interfering with other development efforts or the main staging environment.
Internally, the PR Generator (or the CI/CD action orchestrating it) interacts with your deployment platform. For Vercel, it’s an API call to their service, passing the build artifacts and associated metadata (like the PR number). Vercel then handles the provisioning of a temporary deployment infrastructure. For other platforms, this might involve spinning up Docker containers on a Kubernetes cluster, provisioning ephemeral VMs, or deploying to serverless functions. The key is that the environment is ephemeral and tied to the specific PR.
The exact levers you control are primarily within your CI/CD configuration. You define:
- When the preview environment is triggered (e.g.,
on: pull_request). - What gets deployed (which branch, which commit).
- How it’s deployed (the build commands, the target platform, environment variables).
- How it’s accessed (e.g., Vercel’s auto-generated URLs, custom domain mapping for previews, or even proxying services to expose internal APIs).
- When it’s cleaned up (often via the CI/CD platform automatically closing deployments when a PR is closed or merged, or through explicit teardown steps).
A common pattern is to use a service that automatically comments the preview URL back onto the pull request. This makes it incredibly easy for reviewers to find and access the environment. For example, the Vercel action above will often do this automatically by leveraging the github-token.
The most surprising true thing about preview environments is their ability to drastically reduce integration bugs by shifting testing from a shared staging environment to isolated, production-like instances. This makes it much easier to catch regressions and unexpected interactions early in the development cycle, as the environment for a PR is a near-perfect replica of what will eventually be deployed to production, without any interference from other in-progress work.
The next step is often integrating automated end-to-end tests that run against these ephemeral preview environments.