How the prerelease works

Prerelease status for Workflows: versioning under 0.x, where workflow data lives, what guards enforce today, and who runs the effect runtime.

Workflows is a prerelease. Keep every @sanity/workflow-* package used by one application on the same version. Review release notes and required migrations before upgrading, and upgrade every reader before deploying a writer that requires a newer reader model.

The public Workflows packages release as one fixed stack. Their shared runtime dependencies are exact-version peers, so install the packages your application uses explicitly and keep their versions identical. Packages remain on 0.x: breaking API changes use minor releases and are listed in the release notes and package changelogs.

Persisted workflow documents have a stricter contract than the package APIs: stored shapes grow additively, and reader-floor changes require a reader-first rollout rather than discarding in-flight instances.

Authored configs use WorkflowConfigInput; each WorkflowDeploymentInput requires a reviewed literal. Use expectedMinReaderModel: 4 for definitions on the baseline, and raise it only after the reader-first rollout required by a selected definition. defineWorkflowConfig returns a parsed WorkflowConfig, and the selected deployment is checked before deployment work begins.

The fire-action, abort, set-stage, and reset-activity commands resolve an existing instance by ID, so they do not recheck a config deployment acknowledgement.

• Keep the value literal. Do not import DATA_MODEL_MIN_READER, because a dependency upgrade must not silently acknowledge a higher floor.

Upgrade every Studio, CLI, MCP server, Function, server, and application that reads the workflow resource. Upgrade the producer and deploy definitions last.

A non-empty roles list on an assignee or assignees field raises that definition and its instances to reader model 8. Definitions without this facet remain on the model-4 baseline. See Assignment eligibility.

• Upgrade every Studio, CLI, MCP server, Function, and other runtime that shares the workflow resource to 0.30 or later. Confirm that the deployment uses a dataset resource and can read the project member and user directories.
• Change the reviewed deployment literal to expectedMinReaderModel: 8. MCP deployments pass 8 as the optional tool argument.
• Add the non-empty roles list and redeploy. Existing runs stay pinned to the definition version they started with.

Without the model-8 acknowledgement, deployment rejects before writing. A reader older than model 8 refuses documents that carry the facet.

Model 5 adds dueDate and dueDatetime without raising the reader floor. Upgrade every reader before deploying a definition that uses either kind. An older engine rejects the unfamiliar field kind rather than silently treating it as date or datetime.

Model 4 changes readiness storage and live principal identity. Existing live identity values resolve through the project directory and are rewritten on their next engine commit. History remains unchanged.

// sanity.workflow.ts
import type {WorkflowDeploymentInput} from '@sanity/workflow-engine'
import {defineWorkflowConfig} from '@sanity/workflow-engine/define'
import {myWorkflow} from './workflow'

const production = {
  name: 'production',
  tag: 'prod',
  expectedMinReaderModel: 4,
  workflowResource: {type: 'dataset', id: 'yourprojectid.workflows'},
  definitions: [myWorkflow],
} satisfies WorkflowDeploymentInput

export default defineWorkflowConfig({deployments: [production]})

For a direct engine deployment, acknowledge the same reader model:

import {engine} from './engine'
import {myWorkflow} from './workflow'

await engine.deployDefinitions({
  expectedMinReaderModel: 4,
  definitions: [myWorkflow],
})

During the prerelease, each deployment chooses where its engine-owned state lives.

• Definitions and instances: stored as Sanity documents in the deployment’s workflowResource. A dedicated dataset is common, but the configured resource is the authority.
• Deployment partitions: every definition and instance carries the deployment tag. Different tags can share one workflow resource without sharing workflow state.
• Organization-wide content: a workflow can coordinate documents across datasets, projects, and resource types such as Canvas and Media Library. The content remains in its original resource; workflow fields hold global document references to it. The deployment’s credentials and resource routing must be able to reach every referenced resource.

See Where the workflow lives for the deployment configuration.

No different managed storage destination is part of the public contract today. Treat workflowResource as the prerelease storage contract; if that changes, the release notes will include the destination and migration steps.

Workflow guards let engine-aware surfaces preview holds and explain denied engine commits. See Guards and enforcement for the current enforcement boundary and deployment behavior.

Effects are queued by the engine and completed by a drainer you operate: a Sanity Function, a server, or the CLI during development. A drainer calls drainEffects() with the handlers for the effects it can run. Nothing drains automatically. Run Workflows with Sanity Functions shows how to drain new work with a Document Function and tick existing instances with a Scheduled Function, using a robot token for both.

The Studio plugin requires Sanity 6.3 or later. Use autoStart for fresh documents, and review the Workflows release notes before upgrading.

The @sanity/workflow-blueprint 0.31 package contains provider groundwork, but sanity blueprints deploy cannot deploy Workflows resources until @sanity/blueprints exposes defineWorkflows, the Blueprints API registers the provider, and the staging path is verified. Continue using sanity workflows deploy.

sanity-workflows nuke --deployment deletes a deployment’s definitions, instances, and guards. Use it only when intentionally abandoning all workflow state for that deployment. For disposable prerelease data, reset after upgrading and redeploy with the upgraded engine. To remove one terminal instance without resetting its deployment, use nuke --instance <instanceId>. Abort an in-flight instance before deleting it.