Deployment

Deploying your tasks makes them available to run in production (or staging) environments. Deployment compiles your tasks, packages them into a container image, and registers the new version with Trigger.dev.

Deploy your tasks

Run the deploy command using your package manager:

npx trigger.dev@latest deploy

If you haven’t already, authenticate the CLI with your Trigger.dev account:

npx trigger.dev login

This opens a browser window where you can log in and link your CLI.

Run the deploy command

From the root of your project:

npx trigger.dev deploy

A successful deploy prints output like:

Trigger.dev (3.3.16)
------------------------------------------------------
┌  Deploying project
│
◇  Retrieved your account details for [email protected]
│
◇  Successfully built code
│
◇  Successfully deployed version 20250228.1
│
└  Version 20250228.1 deployed with 4 detected tasks

Trigger tasks using the PROD API key

Copy the production API key from the Trigger.dev dashboard and set it as the TRIGGER_SECRET_KEY environment variable in your application:

TRIGGER_SECRET_KEY="tr_prod_abc123"

Any tasks you trigger will now run against the newly deployed version.

Deploying consists of building your tasks and uploading them to Trigger.dev. This process can take a few seconds to a few minutes depending on the size of your project and whether you are using remote or local builds.

Environments

Trigger.dev supports multiple isolated environments. Each environment has its own API keys, versions, and run history.

Environment	CLI flag	API key prefix	Description
`prod`	(default)	`tr_prod_`	Production environment
`staging`	`--env staging`	`tr_stg_`	Staging environment for pre-production testing
Preview	—	—	Ephemeral per-branch environments for testing and development
`dev`	—	`tr_dev_`	Local development via `trigger.dev dev`

Deploying to staging

npx trigger.dev deploy --env staging

Staging deploys are only available on Hobby and Pro plans on Trigger.dev Cloud.

Staging is a fully independent environment — it has its own version counter and its own current version. To run tasks against staging, use the staging API key:

TRIGGER_SECRET_KEY="tr_stg_abcd123"

Preview environments

For teams that want a separate environment per branch, preview branches create fully isolated environments automatically from your CI pipeline. Configure them in your CI/CD workflow to deploy each branch to its own environment.

Versions

Every deployment creates a new version of all tasks in the project. A version is an immutable snapshot of your task code at a point in time. Version identifiers look like 20250228.1 — the date followed by a sequence number that increments for each deploy on that date within that environment.

Current version

When you deploy, the new version is automatically promoted to become the current version for that environment. All new task runs are dispatched against the current version.

A single environment can only have one current version at a time.

Version locking

Once a task run starts, it is locked to the version that was current at start time. Retries of that run also execute against the same locked version. This means deploying new code never interrupts runs that are already in progress. Child tasks triggered with triggerAndWait or batchTriggerAndWait inherit the parent’s version lock. Fire-and-forget triggers (trigger, batchTrigger) use the current version.

Trigger function	Child task version	Locked
`trigger()`	Current	No
`batchTrigger()`	Current	No
`triggerAndWait()`	Parent version	Yes
`batchTriggerAndWait()`	Parent version	Yes

You can also pin a specific version when triggering a task:

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

Or set a global version override via the environment variable:

TRIGGER_VERSION=20250228.1

Skipping promotion

Deploy a new version without immediately making it the current version using --skip-promotion:

npx trigger.dev deploy --skip-promotion

This is useful for deploying and testing a new version in isolation before rolling it out to all new runs. When you’re ready to promote:

npx trigger.dev promote 20250228.1

Or promote it from the Trigger.dev dashboard using the Promote button on the deployments page.

Local builds

By default, Trigger.dev uses a remote build provider to speed up deployments. You can force a local build if needed:

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

Local builds are a useful fallback when the remote build provider is experiencing availability issues.

Local builds require Docker and Docker Buildx installed on your machine:

Environment variables

Set environment variables for your deployed tasks in the Trigger.dev dashboard under Project > Environment Variables, or sync them automatically using the syncEnvVars, syncVercelEnvVars, or syncSupabaseEnvVars build extensions from @trigger.dev/build. See Build extensions for details.

CI/CD with GitHub Actions

You can automate deployments from GitHub Actions by running the deploy command with a TRIGGER_ACCESS_TOKEN environment variable set to a personal access token.

.github/workflows/deploy.yml

name: Deploy to Trigger.dev

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: npm ci

      - name: Deploy to Trigger.dev
        run: npx trigger.dev@latest deploy
        env:
          TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}

Store your TRIGGER_ACCESS_TOKEN as a GitHub Actions secret. You can generate a personal access token from your Trigger.dev account settings.

For monorepos or projects where trigger.config.ts is not at the repository root, pass the config path explicitly:

npx trigger.dev@latest deploy --config ./apps/worker/trigger.config.ts

Troubleshooting

Dry runs

Inspect what will be built and uploaded without actually deploying:

npx trigger.dev deploy --dry-run

The output will include the path to the build directory, which you can inspect manually.

Debug logs

For verbose output, append --log-level debug to the deploy command. Do not share debug logs publicly — they may contain private information about your project.

npx trigger.dev deploy --log-level debug

Common errors

Failed to build project image: Error building image Check the build logs linked in the error output. If the error is caused by a remote build provider outage, retry with --force-local-build. No loader is configured for ".node" files Native packages cannot be bundled. Add the package to build.external in your trigger.config.ts:

trigger.config.ts

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

export default defineConfig({
  project: "<project ref>",
  build: {
    external: ["your-native-package"],
  },
});

Deployment encountered an error Check the guidance printed below the error message. If you can’t resolve it, open a Help forum post in the Trigger.dev Discord with a link to your deployment.

Getting Started

Writing Tasks

AI Agents & Realtime

Configuration & Deployment

Observability & Management

Self-hosting

Deploy your tasks

Environments

Deploying to staging

Preview environments

Versions

Current version

Version locking

Skipping promotion

Local builds

Environment variables

CI/CD with GitHub Actions

Troubleshooting

Dry runs

Debug logs

Common errors

Build docs developers (and LLMs) love

Getting Started

Writing Tasks

AI Agents & Realtime

Configuration & Deployment

Observability & Management

Self-hosting

​Deploy your tasks

​Environments

​Deploying to staging

​Preview environments

​Versions

​Current version

​Version locking

​Skipping promotion

​Local builds

​Environment variables

​CI/CD with GitHub Actions

​Troubleshooting

​Dry runs

​Debug logs

​Common errors

Build docs developers (and LLMs) love

Deploy your tasks

Environments

Deploying to staging

Preview environments

Versions

Current version

Version locking

Skipping promotion

Local builds

Environment variables

CI/CD with GitHub Actions

Troubleshooting

Dry runs

Debug logs

Common errors