This document describes the complete lifecycle of developing and deploying Trigger.dev tasks, from local development through production deployment. It covers the CLI commands, build pipeline, deployment state machine, container registry configuration, and CI/CD integration.
For information about the Run Engine that executes deployed tasks, see Task Execution Engine. For details about the WebApp control plane, see Web Application.
Trigger.dev supports three deployment modes: local development via trigger.dev dev, containerized deployments via trigger.dev deploy, and self-hosted worker builds via trigger.dev workers build. The deployment process involves building worker code with esbuild, creating a Docker container image, pushing it to a registry, and indexing tasks on the Trigger.dev platform.
Deployment Flow from CLI to Production
Sources: packages/cli-v3/src/commands/deploy.ts1-707 apps/webapp/app/v3/services/initializeDeployment.server.ts1-266 packages/cli-v3/src/deploy/buildImage.ts1-862
trigger.dev devThe trigger.dev dev command starts a local development server on port 8002 that provides hot module reloading and real-time task testing without requiring deployment. The dev server connects to the Trigger.dev platform to register tasks and receive run requests.
Key Components:
packages/cli-v3/src/commands/dev.ts--port)BackgroundWorker in localOnly modeCreateBackgroundWorkerRequestBody/api/v1/dev/dequeue endpoint for tasks to executeThe dev server continuously recompiles the worker code on file changes and automatically re-registers tasks with the platform. This enables rapid iteration during development.
Sources: packages/cli-v3/src/commands/deploy.ts210-707 packages/core/src/v3/schemas/api.ts128-136
The trigger.dev deploy command supports multiple options controlling build behavior, environment selection, and deployment promotion.
| Option | Type | Description | Default |
|---|---|---|---|
--env | prod|staging|preview | Target environment | prod |
--branch | string | Preview branch name | Auto-detected from git |
--local-build | boolean | Build image locally using Docker | false |
--native-build-server | boolean | Use native build server (S3 + worker) | false |
--skip-promotion | boolean | Skip promoting deployment to current | false |
--skip-sync-env-vars | boolean | Skip syncing env vars via syncEnvVars extension | false |
--no-cache | boolean | Disable Docker build cache | false |
--detach | boolean | Return immediately after queuing build | false |
--network | default|none|host | Docker build networking mode | default |
--compression | zstd|gzip | Compression algorithm for image layers | zstd |
--cache-compression | zstd|gzip | Compression algorithm for build cache | zstd |
--compression-level | number | Compression level (0-9) | Automatic |
--force-compression | boolean | Force recompression of all layers | true (for zstd) |
Sources: packages/cli-v3/src/commands/deploy.ts63-90
Trigger.dev supports three distinct build strategies, each optimized for different deployment scenarios:
The default strategy that uses Depot's cloud builders for fast, cached builds without requiring local Docker.
Process:
initializeDeployment() which creates a Depot build via createRemoteImageBuild()externalBuildData containing buildId, buildToken, and projectIdfinalizeDeployment() with the resulting image digestSources: apps/webapp/app/v3/remoteImageBuilder.server.ts1-80 packages/cli-v3/src/deploy/buildImage.ts178-295
Uses the developer's local Docker daemon with docker buildx for full control and debugging.
Process:
docker buildx availability--builder flag (default: trigger)--push or load locally with --load--use-registry-cacheKey Features:
linux/amd64, linux/arm64)Sources: packages/cli-v3/src/deploy/buildImage.ts322-620
A fully server-side build process that eliminates client-side Docker requirements. The CLI uploads a compressed archive of the project, and a worker on the platform performs the build. This mode is activated with the --native-build-server flag.
Process Flow:
createContextArchive() containing the entire workspacePOST /api/v1/artifacts with CreateArtifactRequestBody.tar.gz to S3 using presigned URLartifactKey for later retrievalInitializeDeploymentService with isNativeBuild: true and artifactKeyPENDING statusenqueueBuild() to platform's build worker systemINSTALLING statusBUILDING statusDeploymentService.appendToEventLog()DeploymentEventFromString schemaS2 Event Stream Configuration:
The deployment event stream uses S2 (StreamStore) for real-time log delivery:
Access tokens are scoped to read-only access for the specific deployment stream with 1-hour expiration.
Deployment Event Schema:
The CLI displays logs in real-time, with automatic handling of S2 connection errors and stream completion.
Detached Mode:
When using --detach with native builds, the CLI returns immediately after the build is queued:
This allows the CI/CD pipeline to proceed while the build completes asynchronously. The build status and logs remain accessible via the deployment dashboard URL.
Sources: packages/cli-v3/src/commands/deploy.ts974-1159 apps/webapp/app/routes/api.v1.artifacts.ts1-50 apps/webapp/app/v3/services/initializeDeployment.server.ts147-178 packages/core/src/v3/schemas/api.ts706-730 apps/webapp/app/presenters/v3/DeploymentPresenter.server.ts169-189
Deployments progress through a well-defined state machine tracked by the WorkerDeployment.status field in the database.
Deployment Status Progression
Status Descriptions:
| Status | Description | Transitions To |
|---|---|---|
PENDING | Queued, waiting to start | INSTALLING, CANCELED |
INSTALLING | Installing project dependencies | BUILDING, CANCELED, TIMED_OUT |
BUILDING | Building Docker image | DEPLOYING, CANCELED, FAILED, TIMED_OUT |
DEPLOYING | Pushing to registry and indexing tasks | DEPLOYED, FAILED, TIMED_OUT |
DEPLOYED | Successfully deployed | (final) |
CANCELED | User-canceled deployment | (final) |
FAILED | Build or indexing error | (final) |
TIMED_OUT | Exceeded time limit | (final) |
Key Services:
PENDING or BUILDING statusPENDING → INSTALLING → BUILDINGBUILDING → DEPLOYING → DEPLOYEDFAILED status on errorsCANCELED statusTimeout Management:
Deployments are protected by timeouts managed via TimeoutDeploymentService, which enqueues graphile-worker background jobs:
DEPLOY_QUEUE_TIMEOUT_MS: Applied to PENDING status (native builds waiting in queue)DEPLOY_TIMEOUT_MS: Applied to INSTALLING and BUILDING statuses during active processingWhen a deployment is created, TimeoutDeploymentService.enqueue() schedules a timeout job. If the deployment doesn't complete before the timeout, the job transitions it to TIMED_OUT status. The timeout is extended via TimeoutDeploymentService.enqueue() when the deployment progresses through states (e.g., PENDING → INSTALLING → BUILDING).
On successful deployment or cancellation, the timeout job is removed via TimeoutDeploymentService.dequeue().
Sources: internal-packages/database/prisma/schema.prisma540-576 apps/webapp/app/v3/services/deployment.server.ts110-124 apps/webapp/app/v3/services/initializeDeployment.server.ts230-238 apps/webapp/app/v3/services/finalizeDeploymentV2.server.ts1-229 apps/webapp/app/components/runs/v3/DeploymentStatus.tsx1-166
The build pipeline uses a multi-stage Dockerfile generated by generateContainerfile() that supports Node.js and Bun runtimes.
Multi-Stage Build Architecture
Build Configuration Sources:
The Dockerfile is dynamically generated from the trigger.config.ts configuration:
Build Args Injected at Build Time:
TRIGGER_PROJECT_ID: Project identifierTRIGGER_DEPLOYMENT_ID: Deployment friendly IDTRIGGER_DEPLOYMENT_VERSION: Version string (e.g., 20241201.1)TRIGGER_CONTENT_HASH: Content hash for cachingTRIGGER_PROJECT_REF: External project referenceTRIGGER_API_URL: Platform API endpointTRIGGER_SECRET_KEY: API key for authenticationTRIGGER_PREVIEW_BRANCH: Branch name for preview environmentsNODE_EXTRA_CA_CERTS: Custom CA certificates pathTurbo Prune Optimization:
When using the native build server, the CLI uses turbo prune to create a minimal build context containing only the necessary workspace dependencies. This significantly reduces upload size and build time.
Sources: packages/cli-v3/src/deploy/buildImage.ts629-800 packages/cli-v3/src/commands/workers/build.ts1-475
Trigger.dev supports multiple container registries with automatic ECR repository creation for AWS-based deployments.
Registry Configuration Types
ECR Repository Auto-Creation:
When using AWS ECR, Trigger.dev automatically creates repositories with optimal configuration:
{namespace}/{projectRef} (e.g., trigger-prod/proj_abc123)IMMUTABLE to prevent tag overwritesAssumeRoleCommandImage Tag Format:
{host}/{namespace}/{projectRef}:{version}.{envType}.{shortCode}
Example: 123456789012.dkr.ecr.us-east-1.amazonaws.com/trigger-prod/proj_abc123:20241201.1.prod.def456
Cross-Account ECR Access:
For multi-account AWS setups, Trigger.dev can assume a role in the target account:
The session is automatically managed with a unique session name and 1-hour expiration.
Sources: apps/webapp/app/v3/getDeploymentImageRef.server.ts1-634 apps/webapp/app/v3/registryConfig.server.ts1-45 apps/webapp/test/getDeploymentImageRef.test.ts1-211
The deployment process involves several coordinated services and API endpoints:
Deployment API Flow
Key Services:
| Service | Purpose | File Path |
|---|---|---|
InitializeDeploymentService | Creates deployment record, generates image ref, optionally creates Depot build or enqueues native build | apps/webapp/app/v3/services/initializeDeployment.server.ts19-282 |
DeploymentService | Manages deployment progression (PENDING → INSTALLING → BUILDING), event log appending, and registry credential generation | apps/webapp/app/v3/services/deployment.server.ts25-391 |
FinalizeDeploymentV2Service | Pushes image to registry via Depot (if needed) and triggers task indexing | apps/webapp/app/v3/services/finalizeDeploymentV2.server.ts19-229 |
FinalizeDeploymentService | Updates deployment to DEPLOYED status, links worker, and promotes deployment | apps/webapp/app/v3/services/finalizeDeployment.server.ts16-113 |
StartDeploymentIndexingService | Registers tasks with the platform by running the worker container | Referenced in deploy flow |
ChangeCurrentDeploymentService | Promotes deployment to "current" version for the environment | apps/webapp/app/v3/services/finalizeDeployment.server.ts8 |
FailDeploymentService | Transitions deployment to FAILED status on errors | Referenced in services |
TimeoutDeploymentService | Manages deployment timeouts via graphile-worker jobs | apps/webapp/app/v3/services/deployment.server.ts110-124 |
Deployment Event Log:
The DeploymentService provides event log functionality for native builds and GitHub integration deployments:
Events are stored in S2 (StreamStore) with basin name from S2_DEPLOYMENT_LOGS_BASIN_NAME and stream path projects/{projectRef}/deployments/{shortCode}. Access tokens are cached in Redis with 59-minute TTL for efficient reuse.
The event log allows real-time streaming of build progress to the CLI and dashboard, with automatic fallback for legacy log formats.
API Endpoints:
| Endpoint | Method | Purpose |
|---|---|---|
/api/v1/deployments | POST | Initialize deployment |
/api/v1/deployments/:id/progress | POST | Progress deployment through states |
/api/v2/deployments/:id/finalize | POST | Finalize and push to registry |
/api/v1/deployments/:id/index | POST | Index tasks from built image |
/api/v1/deployments/:id | GET | Get deployment status and details |
/api/v1/deployments/:id/cancel | POST | Cancel deployment |
/api/v1/artifacts | POST | Create S3 upload URL for native builds |
Sources: apps/webapp/app/v3/services/initializeDeployment.server.ts1-282 apps/webapp/app/v3/services/deployment.server.ts1-391 apps/webapp/app/v3/services/finalizeDeploymentV2.server.ts1-229 apps/webapp/app/v3/services/finalizeDeployment.server.ts1-113 apps/webapp/app/routes/api.v1.deployments.$deploymentId.progress.ts1-70
Environment variables are managed through multiple systems: local .env files, trigger.config.ts, and the syncEnvVars extension for automatic synchronization.
Environment Variable Flow
Environment Variable Types:
build.env): Available during Docker image build, used for compilation and asset generationdeploy.sync.env): Automatically synced to the target environment's variable storedeploy.sync.parentEnv): Synced to parent environment (for preview branch deployments)EnvironmentVariableValue recordsConfiguration Example:
Sync Process:
During deployment, if deploy.sync is configured:
syncEnvVarsWithServer() with child and parent variablesPOST /api/v1/projects/:projectRef/:envSlug/import-env-varsEnvironmentVariableValue table with override: true--skip-sync-env-vars flagBuilt-In Variable Overrides:
The RuntimeEnvironment.builtInEnvironmentVariableOverrides JSON field allows per-environment customization of Trigger.dev system variables:
Sources: packages/cli-v3/src/commands/deploy.ts404-447 internal-packages/database/prisma/schema.prisma260-340
The CLI includes built-in support for GitHub Actions and other CI/CD systems through automatic output variable generation.
GitHub Actions Integration:
When running in GitHub Actions (detected via isCI from std-env), the CLI automatically sets output variables and environment variables:
GitHub Actions Workflow Example:
Output Variables Available:
| Variable | Description |
|---|---|
deploymentVersion / TRIGGER_DEPLOYMENT_VERSION | Semantic version (e.g., 20241201.1) |
deploymentShortCode / TRIGGER_DEPLOYMENT_SHORT_CODE | 8-character deployment identifier |
deploymentUrl / TRIGGER_DEPLOYMENT_URL | Dashboard link to deployment |
testUrl / TRIGGER_TEST_URL | Dashboard link to test interface |
needsPromotion | "true" if --skip-promotion was used |
Detached Builds:
For long-running builds, use --detach to return immediately after queuing:
This is useful in CI/CD pipelines where you want to proceed with other tasks while the build completes asynchronously. The build status can be monitored via the dashboard URL.
Sources: packages/cli-v3/src/commands/deploy.ts686-707 packages/cli-v3/src/utilities/githubActions.ts
Refresh this wiki
This wiki was recently refreshed. Please wait 1 day to refresh again.