Editorial Workflows release notes

Curated overviews of recent Editorial Workflows prerelease package waves.

Use these notes to upgrade Editorial Workflows safely. Each release lists required migrations before new capabilities. Package changelogs remain the exhaustive API record.

The 0.23 release expands the Workflows tool with definition and history views, makes stage overrides easier from an interactive terminal, and restores Studio workflow actions and assignments.

None. Engine 0.23 keeps data model 4 and reader floor 4. Keep expectedMinReaderModel: 4; no stored workflow data or Studio configuration migration is required.

The Workflows tool adds a Definitions tab with deployed definition details and stage diagrams. Instance detail now carries the document-oriented workflow snapshot, an inline newest-first history feed, and pending-effect controls. The document view links to this detail instead of opening a separate debug event log.

See Workflows tool.

Reference fields, array items, and other Studio document previews no longer add workflow-stage decorations. Current stage remains visible in the form strip, document badge, and Workflows tool.

Run set-stage without --to on an interactive terminal to choose from every stage in the instance’s pinned definition. The current stage is marked and selected initially. Non-interactive use still requires --to.

See Choose an administrative stage override.

Studio can again fire workflow actions and save user assignees when its Sanity client is explicitly bound to a project API host. The fix restores account-global identity resolution for these Studio operations.

The 0.22 release makes CLI reads easier to automate, removes resource-selection friction for instance commands, and makes deployment targets clearer.

None. Engine 0.22 still writes model 4 documents and keeps the reader floor at 4. Keep expectedMinReaderModel: 4; no stored workflow data migration is required.

A stale numeric acknowledgement now reaches the runtime compatibility check, which rejects it with readers-first rollout guidance. The check still accepts only 4.

Review Reader-model rollout.

Use --json with list, show, definition list, and definition show. Show commands return stored documents; list commands return structured row data with resource provenance and a truncated flag. Multi-resource JSON reads fail instead of returning partial results.

See Automate read commands.

diagnose, fire-action, set-stage, abort, and reset-activity now find an instance across every configured workflow resource from its ID alone. --deployment and --tag remain optional narrowers.

See Pick what a command touches.

Deploy progress and completion lines now name the deployment, tag, and workflow resource.

See Deploy.

The 0.21 release changes the persisted reader floor, workflow readiness, identity storage, recovery, and integration APIs.

Engine 0.21 writes model 4 definitions and instances. Upgrade Studio, applications, Functions, servers, CLI processes, and MCP servers first. Then change every deployment acknowledgement to expectedMinReaderModel: 4.

// sanity.workflow.ts
{
  expectedMinReaderModel: 4,
  // workflowResource, definitions, ...
}

Follow Reader-model rollout.

Replace start.allowed with ordered start.requirements. Replace activity requirement records with ordered GROQ requirement arrays. Use singleSubject for one unfinished run of the same definition per subject.

start: {
  requirements: [
    {type: 'singleSubject', name: 'one-open-run'},
    {type: 'groq', name: 'ready', query: '$fields.ready == true'},
  ],
}

See Start conditions.

$actor.id, user assignees, and $assigned now use the account-global sanityUserId. The same user therefore matches across projects, datasets, Canvas, and Media Library.

On project datasets, guard predicates compare the project-local value returned by identity(). The engine localizes projected actor and assignee metadata automatically, so guard authors do not translate IDs.

Existing live identity values resolve through the project directory and converge on their next engine commit. Audit history remains unchanged.

The Studio plugin now requires Sanity 6.3 or later.

See Install the packages.

list_workflow_instances now returns one page with has_more and next_cursor. Keep the same filters and continue until has_more is false.

See The tools.

useProjectMembers(projectId) returns the ProjectMembersState used by the shared member and assignee controls. AssigneePicker is controlled through onChange(nextValue).

See Edit project-member assignments.

resetActivity reruns or skips a terminal activity in the current stage, then continues the cascade. The CLI exposes the same operation as reset-activity.

See Recover a terminal activity.

The Workflows tool can confirm a local subject is still deleted before aborting its orphaned workflow instances.

See Workflows tool.

A parent now reacts after every child created by one spawn commit has settled, rather than observing a partially settled cohort.

The 0.20 release aligns the public Editorial Workflows packages as one runtime stack and updates Studio integration.

Install every @sanity/workflow-* package used by one application at the same version. Shared runtime packages are now exact-version peer dependencies, so dependencies previously installed transitively must be installed explicitly.

npm install @sanity/workflow-engine@0.20.0 @sanity/workflow-react@0.20.0 @sanity/workflow-sdk@0.20.0

pnpm add @sanity/workflow-engine@0.20.0 @sanity/workflow-react@0.20.0 @sanity/workflow-sdk@0.20.0

yarn add @sanity/workflow-engine@0.20.0 @sanity/workflow-react@0.20.0 @sanity/workflow-sdk@0.20.0

bun add @sanity/workflow-engine@0.20.0 @sanity/workflow-react@0.20.0 @sanity/workflow-sdk@0.20.0

See Versions and breaking changes.

Call workflowDefaultDocumentNode() without mapping arguments.

See Add the plugin to your config.

Move autoStart onto each applicable mapping row.

See Configure auto-start.

Remove mappings used only for workflow discovery. Keep a mapping when it customizes a discovered workflow or binds a definition that uses doc.ref instead of a subject field.

See Discover workflows from subjects.

Remove WorkflowStagePreview and the _id projection added solely for workflow badges.

See Current stage in previews.

The Studio plugin discovers deployed workflows whose caller-provided subject accepts a document type in the current Studio schema. Multiple workflows may target the same document type.

See Add the plugin to your config.

Documents with active workflows display their current stage in supported Studio previews.

Interactive commands ask which deployment to use when configuration is ambiguous. Non-interactive commands still require --deployment or --tag.

See Pick what a command touches.

Engine 0.19 adds new runtime capabilities.

Deployment name is now the unique CLI identity. Rename any deployment whose name is duplicated or contains anything other than lowercase letters, digits, or dashes.

A tag may group deployments across resources. Each (workflowResource, tag) pair remains unique. Use --deployment <name> for one deployment. Use --tag <tag> for a tag group. See Deployment names and tags.

# Target one deployment by name
npx sanity-workflows deploy --deployment review-prod

# Target every deployment in a tag group
npx sanity-workflows deploy --tag prod

# Target one deployment by name
pnpm dlx sanity-workflows deploy --deployment review-prod

# Target every deployment in a tag group
pnpm dlx sanity-workflows deploy --tag prod

# Target one deployment by name
yarn dlx sanity-workflows deploy --deployment review-prod

# Target every deployment in a tag group
yarn dlx sanity-workflows deploy --tag prod

# Target one deployment by name
bunx sanity-workflows deploy --deployment review-prod

# Target every deployment in a tag group
bunx sanity-workflows deploy --tag prod

The new progress field requires engine 0.19 readers. Follow Reader-model acknowledgement before deploying it. Existing workflow data needs no migration. Keep expectedMinReaderModel: 2.

// sanity.workflow.ts
{
  name: 'production',
  expectedMinReaderModel: 2,
  // workflowResource, definitions, ...
}

// Direct engine deployment
await engine.deployDefinitions({
  expectedMinReaderModel: 2,
  definitions,
})

Use a progress field to store completion from 0 to 100.

See Fields.

Call ctx.setProgress(...) to update a progress field while an effect handler runs.

See the working handler example.

Call ctx.commitOps(...) to commit field operations while an effect handler runs.

See the working handler example.

Action evaluation can preview whether an action exits the current stage.

The preview identifies the selected transition.

See Activities and actions.

Upgrade every reader before deploying definitions with this release. Readers include Studio, applications, Functions, MCP servers, and CLI processes. Then add expectedMinReaderModel: 2 to every workflow deployment configuration and every direct deployDefinitions() call. Keep the value literal. Follow the reader-first rollout before changing it.

// sanity.workflow.ts
{
  name: 'production',
  expectedMinReaderModel: 2,
  // workflowResource, definitions, ...
}

// Direct engine deployment
await engine.deployDefinitions({
  expectedMinReaderModel: 2,
  definitions,
})

subject is now a field kind. Replace the former required doc.ref subject convention with one workflow-scoped subject field. Without this migration, an existing definition can still run but no longer appears in document pickers or satisfies subject-based start rules when redeployed. See Fields.

Audit start inputs and spawn mappings. Unknown, wrong-kind, non-input, self-filled, and duplicate initial fields now fail instead of being silently discarded.

Studio can automatically start configured workflows when an editor opens a fresh document. Configure autoStart by document type; see Automatically start workflows.

Definitions can use first-class subject fields, typed scalar choice lists, inclusive string/text/number validation bounds, and decision semantics on actions. Effect handlers preserve concrete Sanity client APIs, including Agent Actions. Studio v6, reusable workflow controls, shared project-user resolution, and the redesigned Workflows tool are also included.

Move permission expressions from start.filter to start.allowed. filter now controls browse-time visibility and cannot read $fields; allowed is enforced when an instance starts.

Treat a caller-supplied instanceId as the idempotency key. Retrying the same start resumes it; do not reuse the ID for a different definition or version.

Fix newly rejected definition traps before redeploying, including invalid workflow or guard names, unbound $row reads, out-of-scope spawn reads, and invalid static field paths.

Programmatic starts gain an enforced allowed gate and resumable retries. The dedicated Workflows tool, causal autonomy analysis, runtime persisted-document validation, resource-surface checks for supplied references, and the tag-scoped CLI nuke command are included.

Move every operation, effect, and spawn payload onto an action. Triggered actions are now the only payload mechanism; remove payloads attached directly to transitions or other structure.

Definitions that can be started directly must use the start block. Review start filters against the new start context before redeploying.

Definitions gain explicit start configuration and triggered actions. CLI, MCP, and condition descriptions use one filter vocabulary, while the test bench more closely mirrors guarded engine behavior.