SOP-003: Deploying to Production

Fresh

Document ID: SOP-003 Version: 1.0 Status: Active Last Updated: 2026-02-21

Overview

This SOP covers deploying Trigger.dev tasks to production, managing versions, promoting deployments, and setting up environment variables.

Prerequisites

SOP-001 and SOP-002 completed (project initialized, tasks written)
Tasks tested successfully in development
Production environment variables ready

Deployment Flow

Step-by-Step Procedure

bash

npx trigger.dev@latest login

This opens a browser for authentication. Complete the login flow.

Step 2: Set Production API Key

In your local environment:

bash

export TRIGGER_SECRET_KEY="tr_prod_your_production_key"

Or add to .env.production. Get the prod key from: Dashboard → Your Project → API Keys → Production

Step 3: Deploy

bash

npx trigger.dev@latest deploy

Successful output:

Trigger.dev (3.x.x)
------------------------------------------------------
◇  Retrieved your account details
◇  Successfully built code
◇  Successfully deployed version 20260221.1
└  Version 20260221.1 deployed with 3 detected tasks

Step 4: Add Environment Variables

Your tasks need access to env vars in production. Set them in: Dashboard → Your Project → Environment Variables

Or use config extensions in trigger.config.ts:

// Sync from Vercel automatically
import { syncVercelEnvVars } from "@trigger.dev/build/extensions/core";

export default defineConfig({
  project: "proj_xxx",
  build: {
    extensions: [syncVercelEnvVars()],
  },
});

Step 5: Trigger from Production Backend

Update your backend .env:

bash

TRIGGER_SECRET_KEY="tr_prod_your_production_key"

Triggering code stays the same — only the key changes:

import { tasks } from "@trigger.dev/sdk";

// This now runs against deployed production version
await tasks.trigger("my-task", { data: "payload" });

Step 6: Verify in Dashboard

Visit your Trigger.dev dashboard
Check Deployments tab — new version should show as "Current"
Trigger a test run from the dashboard using production tasks
Confirm run completes successfully

Version Management

Check Current Version

bash

npx trigger.dev@latest deploy --dry-run

Skip Promotion (Deploy Without Going Live)

bash

npx trigger.dev@latest deploy --skip-promotion

Use this to pre-deploy before a scheduled release. The version exists but won't handle new runs.

Promote a Specific Version

bash

npx trigger.dev@latest promote 20260221.1

Or promote from the dashboard's Deployments tab.

Pin a Run to a Specific Version

await myTask.trigger(payload, { version: "20260221.1" });

Global Version Pin (Environment Variable)

bash

TRIGGER_VERSION=20260221.1

Version Locking Rules

Trigger Function	Child Version
`trigger()`	Current (not locked)
`batchTrigger()`	Current (not locked)
`triggerAndWait()`	Parent's version (locked)
`batchTriggerAndWait()`	Parent's version (locked)

Wait functions auto-lock children to prevent version mismatch bugs.

Environment Management

Production vs Staging

bash

# Deploy to prod (default)
npx trigger.dev@latest deploy

# Deploy to staging (Hobby/Pro plans only)
npx trigger.dev@latest deploy --env staging

Each environment has its own:

API keys (tr_prod_xxx vs tr_stg_xxx)
Current version
Run history
Environment variables

Preview Branches

For per-branch isolated environments:

Set TRIGGER_PREVIEW_BRANCH=branch-name in your CI
Each branch gets its own isolated environment
Use the branch-specific API key for triggering

Verification Checklist

[ ] npx trigger.dev login authenticated
[ ] TRIGGER_SECRET_KEY set to production key
[ ] npx trigger.dev deploy completed without errors
[ ] Version shows as "Current" in dashboard
[ ] Environment variables set in dashboard
[ ] Test run from dashboard succeeds
[ ] Backend .env updated with production key

Troubleshooting

"Failed to build project image"

Try local build as fallback:

bash

npx trigger.dev@latest deploy --force-local-build

Requires Docker and Docker Buildx installed.

".node file" loader error

Add the native package to build.external in trigger.config.ts:

export default defineConfig({
  build: { external: ["your-native-package"] }
});

"Cannot find matching keyid" (Node v22 + corepack)

Fix with:

bash

npm i -g corepack@latest

Or downgrade to Node.js 20 LTS.

"Deployment encountered an error"

Check the link in the error message for build logs
Run with debug logs: npx trigger.dev deploy --log-level debug
Join Trigger.dev Discord and post a help thread

SOP-003: Deploying to Production ​

Overview ​

Prerequisites ​

Deployment Flow ​

Step-by-Step Procedure ​

Step 1: Login to CLI ​

Step 2: Set Production API Key ​

Step 3: Deploy ​

Step 4: Add Environment Variables ​

Step 5: Trigger from Production Backend ​

Step 6: Verify in Dashboard ​

Version Management ​

Check Current Version ​

Skip Promotion (Deploy Without Going Live) ​

Promote a Specific Version ​

Pin a Run to a Specific Version ​

Global Version Pin (Environment Variable) ​

Version Locking Rules ​

Environment Management ​

Production vs Staging ​

Preview Branches ​

Verification Checklist ​

Troubleshooting ​

See Also ​

SOP-003: Deploying to Production

Overview

Prerequisites

Deployment Flow

Step-by-Step Procedure

Step 1: Login to CLI

Step 2: Set Production API Key

Step 3: Deploy

Step 4: Add Environment Variables

Step 5: Trigger from Production Backend

Step 6: Verify in Dashboard

Version Management

Check Current Version

Skip Promotion (Deploy Without Going Live)

Promote a Specific Version

Pin a Run to a Specific Version

Global Version Pin (Environment Variable)

Version Locking Rules

Environment Management

Production vs Staging

Preview Branches

Verification Checklist

Troubleshooting

See Also