Preview branches let you create isolated deployed environments for each branch of your code, allowing you to test changes before merging to production.
You can create preview branches manually but normally you'd use a Pull Request workflow that automatically spins up coordinated environments across all your services.
Why use preview branches?
The preview environment is special – it's where you create branches from. Think of it as the parent environment, with each branch living underneath it and inheriting its configuration. Each preview branch has all the features you're used to from other environments – you can trigger runs, set up schedules, test them, use Realtime, and more.
If you're working on independent features or fixes from your team, it's important to have an isolated deployed environment you can test on before merging to production.
Preview branches are even more powerful when your entire stack supports branching – your frontend, database, and background tasks. This allows your team to test complex user journeys, features or emergency fixes in perfect isolation.
Many modern services now support this branching workflow, for example:
Hosting Platforms:
- Vercel - Automatic preview deployments for every Git branch with custom domains
- Netlify - Deploy previews for pull requests with branch-specific environment variables
- Railway - Ephemeral environments with built-in database and service isolation
Database Services:
- Supabase - Full database branching with auth, storage, and real-time features per branch
- Neon - Instant PostgreSQL branches with automatic Vercel integration
- PlanetScale - Schema branching with deploy requests for safe database changes
- Prisma - Platform environments that coordinate schema changes across branching databases
Demo using preview branches with Vercel
In this video, we demonstrate how to use our preview branches with Vercel to sync deployments across an entire stack.
How can I use preview branches?
There are several ways to use them:
- In the dashboard: Create a branch in the dashboard and archive it. Good for long-lived branches. Guide
- CLI manually: Use the
deploycommand and thearchivecommand. Guide - GitHub Actions: Automatically create preview branches from PRs. Guide
The CLI gives you the flexibility to come up with your own workflows that we haven't covered here.
Triggering runs in preview branches
To trigger runs for a preview branch, you need to set two environment variables:
TRIGGER_SECRET_KEY="tr_preview_1234567890"TRIGGER_PREVIEW_BRANCH="your-branch-name"
For edge runtimes that don't support process.env, you can configure the SDK manually:
import { configure } from "@trigger.dev/sdk";configure({ secretKey: "tr_preview_1234567890", previewBranch: "your-branch-name",});
Environment variables and sync
Environment variables set for "Preview" apply to all branches, but you can override them for specific branches. Branch-specific variables take precedence.
You can sync environment variables automatically using build extensions:
// From a custom serviceimport { syncEnvVars } from "@trigger.dev/build/extensions/core";export default defineConfig({ build: { extensions: [ syncEnvVars(async (ctx) => { return await fetchEnvVars(ctx.environment, ctx.branch); }), ], },});// From Vercelimport { syncVercelEnvVars } from "@trigger.dev/build/extensions/core";export default defineConfig({ build: { extensions: [syncVercelEnvVars()], },});
What's next?
Read our complete preview branches guide.
This is a major step forward in our goal of offering deep integrations with your existing tools. Stay tuned for more coming soon.
