
CEO, Trigger.dev

Today we're excited to introduce preview branches to v4 – a new way to create isolated environments for each of your git branches. Each preview branch has all the features you're used to from other environments (like staging or production). That means you can trigger runs, have schedules, queues, test them, use Realtime, etc.
Here's a short video of how to use them with Vercel:
The process to use preview branches looks like this:
- Create a preview branch
- Deploy to the preview branch (1+ times)
- Trigger runs using your Preview API key (
TRIGGER_SECRET_KEY
) and the branch name (TRIGGER_PREVIEW_BRANCH
). - Archive the preview branch when the branch is done.
There are a few ways to do this:
- Automatically: using GitHub Actions (recommended).
- Use the next build command (recommended)
- Manually: in the dashboard and/or using the CLI.
GitHub Actions
This Pull Request workflow file will automatically create, deploy, and archive a preview branch for each PR.
You will need to set the TRIGGER_ACCESS_TOKEN
(starting with tr_pat_
) in GitHub so the CLI works – learn how to create one and set it in GitHub.
Using the next build command
As shown in the video above, you can modify your existing next build command so when you deploy to Vercel it will deploy to Trigger.dev.
The $VERCEL_ENV
value here is automatically set to either production
or preview
by Vercel. You don't need to set TRIGGER_PREVIEW_BRANCH
in your Vercel env vars because we read the VERCEL_GIT_COMMIT_REF
value.
One caveat with this setup is branches won't get automatically archived because we don't know when the branch is finished with. We have limits on the number of active branches (depending on your plan). You can manually archive them on the "Preview branches" page in the dashboard or you can use the npx trigger.dev@v4-beta preview archive
CLI command (e.g. from a GitHub action when a PR is closed).
Triggering runs and using the SDK
You must set the TRIGGER_PREVIEW_BRANCH
and TRIGGER_SECRET_KEY
environment variables in your backend. That allows the SDK to target the correct branch. When using Vercel you don't need to set TRIGGER_PREVIEW_BRANCH
because we read their VERCEL_GIT_COMMIT_REF
value.
When deploying to somewhere that supports process.env
(like Node.js runtimes) you can just set the environment variables:
TRIGGER_SECRET_KEY="tr_preview_1234567890"TRIGGER_PREVIEW_BRANCH="your-branch-name"
If process.env
isn't supported you can use our configure()
function:
import { configure } from "@trigger.dev/sdk";import { myTask } from "./trigger/myTasks";configure({ // WARNING: Never actually hardcode your secret key like this secretKey: "tr_preview_1234567890", previewBranch: "your-branch-name",});async function triggerTask() { await myTask.trigger({ userId: "1234" }); // Trigger a run in your-branch-name}
Environment variables
You can set environment variables for "Preview" so they are applied to all branches and/or for a specific branch. If a value is set for both it will use the specific branch value.

You can set environment variables in a few ways:
- Manually in the dashboard
- Using our syncEnvVars() extension.
- Using our syncVercelEnvVars() extension.
Wrapping up
Preview branches mean Trigger.dev works well with your existing git workflows.
Read more about preview branches in the docs, read our v4 upgrade guide, or drop into our Discord with questions.