triggerdotdev · matt-aitken · Jun 2, 2025 · May 29, 2025 · May 29, 2025 · May 29, 2025
diff --git a/docs/apikeys.mdx b/docs/apikeys.mdx
@@ -11,18 +11,25 @@ Each environment has its own secret key. You can find the value on the API keys
 
 ![How to find your secret key](/images/api-keys.png)
 
+<Note>
+  For preview branches, you need to also set the `TRIGGER_PREVIEW_BRANCH` environment variable as
+  well. You can find the value on the API keys page when you're on the preview branch.
+</Note>
+
 ### Automatically Configuring the SDK
 
 To automatically configure the SDK with your secret key, you can set the `TRIGGER_SECRET_KEY` environment variable. The SDK will automatically use this value when calling API methods (like `trigger`).
 
 ```bash .env
 TRIGGER_SECRET_KEY="tr_dev_…"
+TRIGGER_PREVIEW_BRANCH="my-branch" # Only needed for preview branches
 ```
 
 You can do the same if you are self-hosting and need to change the default URL by using `TRIGGER_API_URL`.
 
 ```bash .env
 TRIGGER_API_URL="https://trigger.example.com"
+TRIGGER_PREVIEW_BRANCH="my-branch" # Only needed for preview branches
 ```
 
 The default URL is `https://api.trigger.dev`.
@@ -37,6 +44,7 @@ import { myTask } from "./trigger/myTasks";
 
 configure({
   secretKey: "tr_dev_1234", // WARNING: Never actually hardcode your secret key like this
+  previewBranch: "my-branch", // Only needed for preview branches
   baseURL: "https://mytrigger.example.com", // Optional
 });
 

diff --git a/docs/deployment/preview-branches-archive.png b/docs/deployment/preview-branches-archive.png
diff --git a/docs/deployment/preview-branches-new.png b/docs/deployment/preview-branches-new.png
diff --git a/docs/deployment/preview-branches.mdx b/docs/deployment/preview-branches.mdx
@@ -0,0 +1,147 @@
+---
+title: "Preview branches"
+description: "Create isolated environments for each branch of your code, allowing you to test changes before merging to production. You can create preview branches manually or automatically from your git branches."
+---
+
+import UpgradeToV4Note from "/snippets/upgrade-to-v4-note.mdx";
+
+<UpgradeToV4Note />
+
+## How does it work?
+
+The Preview environment is special – you create branches from it. We recommend you automatically create a preview branch for each git branch when a Pull Request is opened and then archive it automatically when the PR is merged/closed.
+
+The process to use preview branches looks like this:
+
+1. Create a preview branch
+2. Deploy to the preview branch (1+ times)
+3. Trigger runs using your Preview API key (`TRIGGER_SECRET_KEY`) and the branch name (`TRIGGER_PREVIEW_BRANCH`).
+4. Archive the preview branch when the branch is done.
+
+There are two main ways to do this:
+
+1. Automatically: using GitHub Actions (recommended).
+2. Manually: in the dashboard and/or using the CLI.
+
+### Limits on active preview branches
+
+We restrict the number of active preview branches (per project). You can archive a preview branch at any time (automatically or manually) to unlock another slot.
+
+Once archived you can still view the dashboard for the branch but you can't trigger or execute runs (or other write operations).
+
+This limit exists because each branch has an independent concurrency limit. For the Cloud product these are the limits:
+
+| Plan  | Active preview branches |
+| ----- | ----------------------- |
+| Free  | 0                       |
+| Hobby | 5                       |
+| Pro   | 20 (then paid for more) |
+
+For full details see our [pricing page](https://trigger.dev/pricing).
+
+## Triggering runs and using the SDK
+
+Before we talk about how to deploy to preview branches, one important thing to understand is that you must set the `TRIGGER_PREVIEW_BRANCH` environment variable as well as the `TRIGGER_SECRET_KEY` environment variable.
+
+When deploying to somewhere that supports `process.env` (like Node.js runtimes) you can just set the environment variables:
+
+```bash
+TRIGGER_SECRET_KEY="tr_preview_1234567890"
+TRIGGER_PREVIEW_BRANCH="your-branch-name"
+```
+
+If you're deploying somewhere that doesn't support `process.env` (like some edge runtimes) you can manually configure the SDK:
+
+```ts
+import { configure } from "@trigger.dev/sdk";
+import { myTask } from "./trigger/myTasks";
+
+configure({
+  secretKey: "tr_preview_1234567890", // WARNING: Never actually hardcode your secret key like this
+  previewBranch: "your-branch-name",
+});
+
+async function triggerTask() {
+  await myTask.trigger({ userId: "1234" }); // Trigger a run in your-branch-name
+}
+```
+
+## Preview branches with GitHub Actions (recommended)
+
+This GitHub Action will:
+
+1. Automatically create a preview branch for your Pull Request (if the branch doesn't already exist).
+2. Deploy the preview branch.
+3. Archive the preview branch when the Pull Request is merged/closed.
+
+```yml .github/workflows/trigger-preview-branches.yml
+name: Deploy to Trigger.dev (preview branches)
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+
+jobs:
+  deploy-preview:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js 20.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Deploy preview branch
+        run: npx trigger.dev@v4-beta deploy --env preview
+        env:
+          TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
+```
+
+For this workflow to work, you need to set the following secrets in your GitHub repository:
+
+- `TRIGGER_ACCESS_TOKEN`: A Trigger.dev personal access token (they start with `tr_pat_`). [Learn how to create one and set it in GitHub](/github-actions#creating-a-personal-access-token).
+
+Notice that the deploy command has `--env preview` at the end. We automatically detect the preview branch from the GitHub actions env var.
+
+You can manually specify the branch using `--branch <branch-name>` in the deploy command, but this isn't required.
+
+## Preview branches with the CLI (manual)
+
+### Deploying a preview branch
+
+Creating and deploying a preview branch manually is easy:
+
+```bash
+npx trigger.dev@v4-beta deploy --env preview
+```
+
+This will create and deploy a preview branch, automatically detecting the git branch. If for some reason the auto-detection doesn't work it will let you know and tell you do this:
+
+```bash
+npx trigger.dev@v4-beta deploy --env preview --branch your-branch-name
+```
+
+### Archiving a preview branch
+
+You can manually archive a preview branch with the CLI:
+
+```bash
+npx trigger.dev@v4-beta preview archive
+```
+
+Again we will try auto-detect the current branch. But you can specify the branch name with `--branch <branch-name>`.
+
+## Creating and archiving preview branches from the dashboard
+
+From the "Preview branches" page you can create a branch:
+
+![Preview branches page](/deployment/preview-branches.png)
+![Create preview branch](/deployment/preview-branches-new.png)
+
+You can also archive a branch:
+
+![Archive preview branch](/deployment/preview-branches-archive.png)
diff --git a/docs/deployment/preview-branches.png b/docs/deployment/preview-branches.png
diff --git a/docs/docs.json b/docs/docs.json
@@ -100,6 +100,7 @@
               "deployment/overview",
               "deploy-environment-variables",
               "github-actions",
+              "deployment/preview-branches",
               "deployment/atomic-deployment",
               {
                 "group": "Deployment integrations",

diff --git a/docs/snippets/cli-commands-deploy.mdx b/docs/snippets/cli-commands-deploy.mdx
@@ -4,6 +4,7 @@ import ProjectRefOption from "/snippets/cli-options-project-ref.mdx";
 import EnvFileOption from "/snippets/cli-options-env-file.mdx";
 import ConfigFileOption from "/snippets/cli-options-config-file.mdx";
 import SkipUpdateCheckOption from "/snippets/cli-options-skip-update-check.mdx";
+import BranchOption from "/snippets/cli-options-branch.mdx";
 
 Run the command like this:
 
@@ -56,9 +57,12 @@ npx trigger.dev@latest deploy [path]
 <SkipUpdateCheckOption />
 
 <ParamField body="Environment" type="--env | -e">
-  Defaults to `prod` but you can specify `staging`.
+  Defaults to `prod` but you can specify `staging` or `preview`. If you specify `preview` we will
+  try and automatically detect the branch name from git.
 </ParamField>
 
+<BranchOption />
+
 <ParamField body="Dry run" type="--dry-run">
   Create a deployable build but don't deploy it. Prints out the build path so you can inspect it.
 </ParamField>

diff --git a/docs/snippets/cli-options-branch.mdx b/docs/snippets/cli-options-branch.mdx
@@ -0,0 +1,4 @@
+<ParamField body="Preview branch" type="--branch | -b">
+  When using `--env preview` the branch is automatically detected from git. But you can manually
+  specify it by using this option, e.g. `--branch my-branch` or `-b my-branch`.
+</ParamField>
diff --git a/docs/triggering.mdx b/docs/triggering.mdx
@@ -28,7 +28,7 @@ Trigger tasks **from inside a another task**:
 
 ## Triggering from your backend
 
-When you trigger a task from your backend code, you need to set the `TRIGGER_SECRET_KEY` environment variable. You can find the value on the API keys page in the Trigger.dev dashboard. [More info on API keys](/apikeys).
+When you trigger a task from your backend code, you need to set the `TRIGGER_SECRET_KEY` environment variable. If you're [using a preview branch](/deployment/preview-branches), you also need to set the `TRIGGER_PREVIEW_BRANCH` environment variable. You can find the value on the API keys page in the Trigger.dev dashboard. [More info on API keys](/apikeys).
 
 <Note>
   If you are using Next.js Server Actions [you'll need to be careful with