Skip to main content
Every deployment to Trigger.dev creates an immutable version — a snapshot of all your tasks at a point in time. Version locking ensures that in-progress runs are never affected by new deploys.

​
Version identifiers

Version identifiers combine the date and a sequence number:
IdentifierMeaning
20240313.1March 13 2024, first deploy that day
20240313.2March 13 2024, second deploy that day
20240314.1March 14 2024, first deploy that day
The sequence number resets each day and is scoped per environment. 20240313.1 can exist independently in both dev and prod.

​
How version locking works

When a task run starts, it is locked to the version that was current at that moment. Even if you deploy a dozen new versions while the run is executing, it continues on the same code. Retries of a run also execute against the same locked version. Delayed runs are locked to the version active when they begin executing, not when they were enqueued.

​
Child tasks

How version locking applies to child tasks depends on whether the parent waits for the result:
Trigger functionChild task versionLocked
trigger()Latest (current)No
batchTrigger()Latest (current)No
triggerAndWait()Same as parentYes
batchTriggerAndWait()Same as parentYes
Version-locking child tasks with triggerAndWait and batchTriggerAndWait ensures the parent and child are always running compatible code.

​
Versions in local development

When running the dev server (npx trigger.dev dev), every relevant code change automatically registers a new version. Each task run spawns a dedicated process locked to the version at the time of the run — so hot-reloading your code does not affect in-progress dev runs.

​
Deploying a new version

Running trigger.dev deploy creates a new version and immediately promotes it to the current version for that environment. All new runs after this point execute against the new code. 
npx trigger.dev deploy
# └─ Deploys and promotes 20250314.1 as the current version

​
Skipping promotion

Use --skip-promotion to deploy a new version without making it current. This is useful for staging a deploy and testing it before rolling it out: 
npx trigger.dev deploy --skip-promotion
# └─ Creates 20250314.2, but current version remains 20250314.1
When you are ready to promote, run: 
npx trigger.dev promote 20250314.2
Or promote from the Trigger.dev dashboard. See the Deployment overview for the full deployment workflow.

​
Triggering a specific version

You can target a specific version when triggering a task. This is useful for testing a non-current deployment: 
await myTask.trigger({ foo: "bar" }, { version: "20250314.2" });
To override the version for all triggers in a process, set the environment variable: 
TRIGGER_VERSION=20250314.2

​
Retries

When a task fails and is retried, the retry runs on the same version as the original run. A deploy mid-flight does not change which code your retries execute.

​
Replays

A replay creates a brand-new run from the same payload, but uses the current version of the code rather than the version of the original run. Use replays to re-run a task after fixing a bug without needing to re-trigger it manually. You can replay failed runs from the Trigger.dev dashboard or via the Runs API.

Build docs developers (and LLMs) love

Get started for freeTalk to us