Versioning

Every job and workflow in Strait is versioned. When you update a job’s configuration, the previous version is snapshotted so that in-flight runs continue to execute with the config they were enqueued under.

Dual Versioning

Each job and workflow has two version identifiers:

Field	Type	Purpose
`version`	Integer	Auto-incrementing counter (1, 2, 3, …). Used for ordering and internal references.
`version_id`	String	Globally unique nanoid (`ver_k8f2m9x1p3`). Used as the public-facing identifier.

The integer version is predictable and easy to reason about. The version_id is a 16-character string (4-char prefix + 12-char nanoid using 0-9a-z alphabet) that’s safe to expose in URLs and APIs without leaking ordering information.

Version Lifecycle

CreateJob → version=1, version_id=ver_abc123def456
UpdateJob → version=2, version_id=ver_xyz789ghi012  (old config snapshotted)
UpdateJob → version=3, version_id=ver_mno345pqr678  (old config snapshotted)

On each UpdateJob, the current configuration is snapshotted to the job_versions table before the update is applied. This means:

job_versions contains the full config for versions 1, 2, … (N-1)
The live jobs table always has the current (latest) version

Atomic Versioning

When a run is enqueued, it captures the job’s current version and version_id:

TriggerJob(job_id=X) → run.job_version=2, run.job_version_id=ver_xyz789ghi012

When the executor picks up the run, it reads the job config at that version from the snapshot table:

job, err := store.GetJobAtVersion(ctx, run.JobID, run.JobVersion)

This prevents a common race condition: if you update a job’s endpoint URL while runs are queued, those runs still execute against the old endpoint.

Fallback Behavior

If no snapshot exists for the requested version (e.g., version 1 before snapshotting was implemented), the executor falls back to reading the live jobs table. This ensures backwards compatibility.

Version Policy

Each job and workflow has a version_policy that controls how queued runs interact with version updates:

Policy	Behavior	Use Case
`pin` (default)	Runs execute with the version they were enqueued under	Safety-first deployments
`latest`	Queued runs upgrade to the latest version at dequeue time	Fast rollouts, non-breaking changes
`minor`	Upgrade only if the new version is marked `backwards_compatible`	Controlled rollouts

`pin` (Default)

The safest option. Runs always execute with the exact configuration they were enqueued under. A job update never affects already-queued runs.

Enqueue run (job at v2) → Update job to v3 → Dequeue → Run executes with v2 config

`latest`

Queued runs automatically upgrade to the current version when dequeued. Useful when you want all runs to use the latest config regardless of when they were enqueued.

Enqueue run (job at v2) → Update job to v3 → Dequeue → Run executes with v3 config

`minor`

A middle ground. Queued runs upgrade only if the new version has backwards_compatible = true. This lets you control which updates are safe for in-flight runs.

Enqueue run (job at v2) → Update job to v3 (backwards_compatible=true) → Dequeue → Run upgrades to v3
Enqueue run (job at v2) → Update job to v3 (backwards_compatible=false) → Dequeue → Run stays at v2

Setting Version Policy

curl -X POST https://strait.dev/v1/jobs \
  -d '{
    "name": "my-job",
    "version_policy": "latest",
    ...
  }'

Or update an existing job:

curl -X PATCH https://strait.dev/v1/jobs/job_123 \
  -d '{"version_policy": "latest"}'

Version policy is enforced at dequeue time by the worker dispatch path. pin is still the safest default and is applied automatically when no policy is provided.

Version Snapshots

The job_versions table stores a full snapshot of the job configuration at each version:

endpoint_url, fallback_endpoint_url
max_attempts, timeout_secs
tags, payload_schema
max_concurrency, execution_window_cron
rate_limit_max, rate_limit_window_secs
retry_strategy, retry_delays_secs
environment_id, group_id
enabled
version_id, backwards_compatible

Snapshots are created automatically on UpdateJob. The first version (at creation time) is captured when the first update occurs.

Browsing Versions

List all versions of a job:

curl https://strait.dev/v1/jobs/job_123/versions \
  -H "Authorization: Bearer strait_..."

Response:

[
  {
    "id": "ver_abc",
    "job_id": "job_123",
    "version": 2,
    "version_id": "ver_xyz789ghi012",
    "endpoint_url": "https://old.example.com/webhook",
    "max_attempts": 3,
    "backwards_compatible": false,
    "created_at": "2025-01-15T10:30:00Z"
  },
  {
    "id": "ver_def",
    "job_id": "job_123",
    "version": 1,
    "version_id": "ver_abc123def456",
    "endpoint_url": "https://original.example.com/webhook",
    "max_attempts": 5,
    "backwards_compatible": false,
    "created_at": "2025-01-10T08:00:00Z"
  }
]

Workflow Versioning

Workflows use the same dual version model (version + version_id) and snapshot workflow definitions, including step graphs. Every time you update a workflow via PATCH /v1/workflows/{workflowID}, the version increments and the previous step graph is preserved.

Inspecting versions

GET /v1/workflows/{workflowID}/versions — list all version snapshots
GET /v1/workflows/{workflowID}/versions/{versionID} — get a specific version
GET /v1/workflows/{workflowID}/versions/{versionID}/steps — get the step graph for a version
GET /v1/workflows/{workflowID}/active-versions — list versions that have active (pending, running, or paused) runs, with status breakdowns

Breaking change detection

When you update a workflow, the response includes information about in-flight runs on the previous version:

{
  "id": "wf_abc",
  "version": 4,
  "active_runs_on_previous_version": 3,
  "previous_version_id": "ver_xyz"
}

The active_runs_on_previous_version field appears whenever there are non-terminal runs still executing on the version that was just replaced. This gives you immediate visibility into whether your update might affect running workflows. To explicitly acknowledge a breaking update, set breaking_change to true in the request body:

PATCH /v1/workflows/{workflowID}
{
  "steps": [...],
  "breaking_change": true
}

When breaking_change is true and active runs exist on the previous version, Strait records a workflow.updated_breaking audit event with the previous version ID, active run count, and new version number. This makes breaking deployments visible in your audit log.

Run Provenance

Every run records which version it was enqueued under:

{
  "id": "run_123",
  "job_id": "job_456",
  "job_version": 2,
  "job_version_id": "ver_xyz789ghi012",
  "status": "completed"
}

This gives you exact traceability: you can always determine which configuration a run executed with, even if the job has been updated many times since.

Getting Started

Core Concepts

More Concepts

Configuration

Guides

AI Agents

Integrations

Operations

Development

Dual Versioning

Version Lifecycle

Atomic Versioning

Fallback Behavior

Version Policy

`pin` (Default)

`latest`

`minor`

Setting Version Policy

Version Snapshots

Browsing Versions

Workflow Versioning

Inspecting versions

Breaking change detection

Run Provenance

​Dual Versioning

​Version Lifecycle

​Atomic Versioning

​Fallback Behavior

​Version Policy

​pin (Default)

​latest

​minor

​Setting Version Policy

​Version Snapshots

​Browsing Versions

​Workflow Versioning

​Inspecting versions

​Breaking change detection

​Run Provenance

Dual Versioning

Version Lifecycle

Atomic Versioning

Fallback Behavior

Version Policy

`pin` (Default)

`latest`

`minor`

Setting Version Policy

Version Snapshots

Browsing Versions

Workflow Versioning

Inspecting versions

Breaking change detection

Run Provenance