Deployment Overview

Complete guide to deploying Trigger.dev tasks.

Deploying 101

npx trigger.dev login       # Authenticate
npx trigger.dev deploy      # Deploy

Triggering Deployed Tasks

Copy the PROD API key from the Trigger.dev dashboard and set:

TRIGGER_SECRET_KEY="tr_prod_abc123"

Then trigger tasks normally:

import { myTask } from "./trigger/tasks";
await myTask.trigger({ foo: "bar" });

Versions

Each deploy creates a new version — a snapshot of all your tasks.

Current Version

• One "current" version per environment
• New task runs execute against the current version
• Once a run starts, it's locked to that version (retries use same version)
• "Replay" in dashboard creates a new run locked to the current version

Version Locking

Specify a version when triggering:

await myTask.trigger({ foo: "bar" }, { version: "20250228.1" });

Or set globally:

TRIGGER_VERSION=20250228.1

Child Tasks & Version Locking

Function	Child version	Locked?
trigger()	Current	No
batchTrigger()	Current	No
triggerAndWait()	Same as parent	Yes
batchTriggerAndWait()	Same as parent	Yes

Skip Promotion

Deploy without setting as current:

npx trigger.dev deploy --skip-promotion

# Promote when ready:
npx trigger.dev promote 20250228.1

See Atomic Deployment for staged rollout patterns.

Staging Deploys

npx trigger.dev deploy --env staging

Use staging API key:

TRIGGER_SECRET_KEY="tr_stg_abcd123"

INFO

Staging requires Hobby or Pro plan on Trigger.dev Cloud.

For additional environments, use preview branches.

Local Builds

By default, builds use a remote build provider. Force local:

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

Requirements: Docker + Docker Buildx

Environment Variables

Add via:

• Trigger.dev dashboard → Environment Variables
• syncEnvVars build extension
• syncVercelEnvVars

Troubleshooting

Dry Run

npx trigger.dev deploy --dry-run
# Outputs build dir path for inspection

Common Errors

Failed to build project image

• Check full build logs linked in error output
• Try --force-local-build as fallback

No loader is configured for ".node" files

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

build: { external: ["your-native-package"] }

Cannot find matching keyid

• Node.js v22 + corepack issue
• Fix: downgrade to Node.js v20, or npm i -g corepack@latest