diff --git a/docs/apikeys.mdx b/docs/apikeys.mdx
index 9d4df925c5..5b9eeef1a1 100644
--- 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
+
+ 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.
+
+
### 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/cli-preview-archive.mdx b/docs/cli-preview-archive.mdx
new file mode 100644
index 0000000000..3b21c08c08
--- /dev/null
+++ b/docs/cli-preview-archive.mdx
@@ -0,0 +1,62 @@
+---
+title: "CLI preview archive command"
+sidebarTitle: "preview archive"
+description: "The `trigger.dev preview archive` command can be used to archive a preview branch."
+---
+
+import UpgradeToV4Note from "/snippets/upgrade-to-v4-note.mdx";
+import ProjectPathArg from "/snippets/cli-args-project-path.mdx";
+import CommonOptions from "/snippets/cli-options-common.mdx";
+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:
+
+
+
+```bash npm
+npx trigger.dev@v4-beta preview archive
+```
+
+```bash pnpm
+pnpm dlx trigger.dev@v4-beta preview archive
+```
+
+```bash yarn
+yarn dlx trigger.dev@v4-beta preview archive
+```
+
+
+
+It will archive the preview branch, automatically detecting the branch name from git. You can manually specify the branch using the `--branch` option.
+
+## Arguments
+
+```
+npx trigger.dev@v4-beta preview archive [path]
+```
+
+
+
+## Options
+
+
+
+
+
+
+
+
+
+
+
+### Common options
+
+These options are available on most commands.
+
+
diff --git a/docs/context.mdx b/docs/context.mdx
index b325f950b3..bd9d3547ed 100644
--- a/docs/context.mdx
+++ b/docs/context.mdx
@@ -3,10 +3,11 @@ title: "Context"
description: "Get the context of a task run."
---
-Context (`ctx`) is a way to get information about a run.
+Context (`ctx`) is a way to get information about a run.
-The context object does not change whilst your code is executing. This means values like `ctx.run.durationMs` will be fixed at the moment the `run()` function is called.
+ The context object does not change whilst your code is executing. This means values like
+ `ctx.run.durationMs` will be fixed at the moment the `run()` function is called.
@@ -17,7 +18,6 @@ import { task } from "@trigger.dev/sdk/v3";
export const parentTask = task({
id: "parent-task",
run: async (payload: { message: string }, { ctx }) => {
-
if (ctx.environment.type === "DEVELOPMENT") {
return;
}
@@ -32,7 +32,8 @@ export const parentTask = task({
- The exported function name of the task e.g. `myTask` if you defined it like this: `export const myTask = task(...)`.
+ The exported function name of the task e.g. `myTask` if you defined it like this: `export
+ const myTask = task(...)`.
The ID of the task.
@@ -93,13 +94,16 @@ export const parentTask = task({
The [maximum number of attempts](/triggering#maxattempts) allowed for this task run.
- The duration of the task run in milliseconds when the `run()` function is called. For live values use the [usage SDK functions](/run-usage).
+ The duration of the task run in milliseconds when the `run()` function is called. For live
+ values use the [usage SDK functions](/run-usage).
- The cost of the task run in cents when the `run()` function is called. For live values use the [usage SDK functions](/run-usage).
+ The cost of the task run in cents when the `run()` function is called. For live values use the
+ [usage SDK functions](/run-usage).
- The base cost of the task run in cents when the `run()` function is called. For live values use the [usage SDK functions](/run-usage).
+ The base cost of the task run in cents when the `run()` function is called. For live values
+ use the [usage SDK functions](/run-usage).
The [version](/versioning) of the task run.
@@ -132,6 +136,40 @@ export const parentTask = task({
The type of the environment (PRODUCTION, STAGING, DEVELOPMENT, or PREVIEW).
+
+ If the environment is `PREVIEW` then this will be the branch name.
+
+
+
+
+ The name of the commit author.
+
+
+ The message of the commit.
+
+
+ The ref of the commit.
+
+
+ The SHA of the commit.
+
+
+ Whether the commit is dirty, i.e. there are uncommitted changes.
+
+
+ The remote URL of the repository.
+
+
+ The number of the pull request.
+
+
+ The title of the pull request.
+
+
+ The state of the pull request (open, closed, or merged).
+
+
+
diff --git a/docs/deployment/preview-branches-archive.png b/docs/deployment/preview-branches-archive.png
new file mode 100644
index 0000000000..4dcb38cb0c
Binary files /dev/null and b/docs/deployment/preview-branches-archive.png differ
diff --git a/docs/deployment/preview-branches-new.png b/docs/deployment/preview-branches-new.png
new file mode 100644
index 0000000000..baeabe3f7d
Binary files /dev/null and b/docs/deployment/preview-branches-new.png differ
diff --git a/docs/deployment/preview-branches.mdx b/docs/deployment/preview-branches.mdx
new file mode 100644
index 0000000000..d6fa098030
--- /dev/null
+++ b/docs/deployment/preview-branches.mdx
@@ -0,0 +1,203 @@
+---
+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";
+
+
+
+## How to use preview branches
+
+The preview environment is special – you create branches from it. The branches you create live under the preview environment and have all the features you're used to from other environments (like staging or production). That means you can trigger runs, have schedules, test them, use Realtime, etc.
+
+
+
+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 – or you can upgrade your plan.
+
+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 ` 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 `.
+
+## Creating and archiving preview branches from the dashboard
+
+From the "Preview branches" page you can create a branch:
+
+
+
+
+You can also archive a branch:
+
+
+
+## Environment variables
+
+You can set environment variables for "Preview" and they will get applied to all branches (existing and new). You can also set environment variables for a specific branch. If they are set for both then the branch-specific variables will take precedence.
+
+
+
+These can be set manually in the dashboard, or automatically at deploy time using the [syncEnvVars()](/config/extensions/syncEnvVars) or [syncVercelEnvVars()](/config/extensions/syncEnvVars#syncvercelenvvars) build extensions.
+
+### Sync environment variables
+
+Full instructions are in the [syncEnvVars()](/config/extensions/syncEnvVars) documentation.
+
+```ts trigger.config.ts
+import { defineConfig } from "@trigger.dev/sdk";
+// You will need to install the @trigger.dev/build package
+import { syncEnvVars } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+ //... other config
+ build: {
+ // This will automatically detect and sync environment variables
+ extensions: [
+ syncEnvVars(async (ctx) => {
+ // You can fetch env variables from a 3rd party service like Infisical, Hashicorp Vault, etc.
+ // The ctx.branch will be set if it's a preview deployment.
+ return await fetchEnvVars(ctx.environment, ctx.branch);
+ }),
+ ],
+ },
+});
+```
+
+### Sync Vercel environment variables
+
+You need to set the `VERCEL_ACCESS_TOKEN`, `VERCEL_PROJECT_ID` and `VERCEL_TEAM_ID` environment variables. You can find these in the Vercel dashboard. Full instructions are in the [syncVercelEnvVars()](/config/extensions/syncEnvVars#syncvercelenvvars) documentation.
+
+The extension will automatically detect a preview branch deploy from Vercel and sync the appropriate environment variables.
+
+```ts trigger.config.ts
+import { defineConfig } from "@trigger.dev/sdk";
+// You will need to install the @trigger.dev/build package
+import { syncVercelEnvVars } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+ //... other config
+ build: {
+ // This will automatically detect and sync environment variables
+ extensions: [syncVercelEnvVars()],
+ },
+});
+```
diff --git a/docs/deployment/preview-branches.png b/docs/deployment/preview-branches.png
new file mode 100644
index 0000000000..8dd62563ce
Binary files /dev/null and b/docs/deployment/preview-branches.png differ
diff --git a/docs/deployment/preview-environment-branches.png b/docs/deployment/preview-environment-branches.png
new file mode 100644
index 0000000000..99c81f7a2d
Binary files /dev/null and b/docs/deployment/preview-environment-branches.png differ
diff --git a/docs/deployment/preview-environment-variables.png b/docs/deployment/preview-environment-variables.png
new file mode 100644
index 0000000000..11283356ab
Binary files /dev/null and b/docs/deployment/preview-environment-variables.png differ
diff --git a/docs/docs.json b/docs/docs.json
index 7726ed78a5..12916eccbf 100644
--- 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",
@@ -144,6 +145,7 @@
"cli-dev-commands",
"cli-deploy-commands",
"cli-promote-commands",
+ "cli-preview-archive",
"cli-whoami-commands",
"cli-logout-commands",
"cli-list-profiles-commands",
diff --git a/docs/snippets/cli-commands-deploy.mdx b/docs/snippets/cli-commands-deploy.mdx
index 78289eebc6..95efc59bd3 100644
--- 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]
- 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.
+
+
Create a deployable build but don't deploy it. Prints out the build path so you can inspect it.
diff --git a/docs/snippets/cli-options-branch.mdx b/docs/snippets/cli-options-branch.mdx
new file mode 100644
index 0000000000..f725b8dfe7
--- /dev/null
+++ b/docs/snippets/cli-options-branch.mdx
@@ -0,0 +1,4 @@
+
+ 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`.
+
diff --git a/docs/triggering.mdx b/docs/triggering.mdx
index f5e251fec7..10634f0284 100644
--- 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).
If you are using Next.js Server Actions [you'll need to be careful with