Changelog #105

·

Preview branches

Isolated environments for each of your git branches.

Matt Aitken

Matt Aitken

CEO, Trigger.dev

Image for Preview branches

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:

  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 a few ways to do this:

  1. Automatically: using GitHub Actions (recommended).
  2. Use the next build command (recommended)
  3. 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.

.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 }}

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.

package.json

"scripts": {
"build": "next build && npx [email protected] deploy --env $VERCEL_ENV",
},

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.

Environment variables

You can set environment variables in a few ways:

  1. Manually in the dashboard
  2. Using our syncEnvVars() extension.
  3. 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.

#104

Ready to start building?

Build and deploy your first task in 3 minutes.

Get started now