Deployments, tags, and resources

How a deployment binds definitions to a Sanity resource: name versus tag, the storage partition that keeps environments apart, and the aliases that point a definition at real content.

A deployment is one entry in the deployments array of a sanity.workflow.ts config. It binds a set of workflow definitions to the Sanity resource that stores them, gives their instances an environment partition to live in, and declares the engine data model every runtime reading that resource can interpret. Every CLI command reaches a definition through a deployment.

This page explains the model that config expresses. To install the CLI and write your first config, see Configure and deploy workflow definitions.

A deployment has two identifiers and they answer different questions. name is its unique CLI identity, so it always resolves to exactly one deployment. Use --deployment <name> when a command must target one. tag labels the stored definition and instance partition, and may group deployments across different workflow resources.

Because one tag can cover several deployments and a name never can, the two selectors do not behave the same way on every command. The Workflow CLI command reference has the full matrix, including which commands treat a tag as a group and which require it to resolve to exactly one deployment.

One pair must stay unique: no two deployments may share both a workflowResource and a tag. That pair is the storage partition, so two deployments sharing it would write into the same place and fight over definition versions. The config rejects the collision at load and names both entries.

Environments are kept apart by that pair, not by anything inside the definition. The same definition deployed under two tags produces two independent sets of instances that never see each other. To run one definition in both staging and production, either point the two deployments at different datasets or keep one dataset and give them different tags.

The documents a workflow owns, its deployed definitions and the instances it spawns, are written to the workflowResource: one Sanity resource. The CLI derives the project and dataset of its client from it, so every deployment must declare it. A dataset, with id <projectId>.<dataset>, is the common case. Canvas, media-library, and dashboard resources are accepted too. Point it at a dedicated dataset when you would rather keep engine documents out of the dataset your editors work in.

Content a workflow reads and writes is addressed through resourceAliases. A definition points at content by alias name rather than a hardcoded dataset, as in {id: '@content:article-123', type: 'article'}, and resourceAliases binds each alias to a real resource. Using aliases is what lets the same definition ship to production or staging by binding differently.

You only need an alias for content in a different resource from the workflowResource. A definition can reference a document in the same resource by bare id, because bare ids root at the workflowResource. So the smallest single-dataset setup is a workflowResource and definitions, with no resourceAliases at all.

At deploy, each @<handle>: reference expands to the bound resource, and nothing alias-shaped survives into the deployed definition. A deployment that references an alias it does not bind fails rather than deploying against the wrong resource.

Two alias patterns look similar and do different jobs. Two aliases in one deployment mean one workflow touching more than one resource at once, such as a cross-brand publish reading two datasets together; see One workflow across resources. The same alias name bound differently across deployments means one workflow shipped to several equivalent environments. Coordinate content across projects and datasets is the guide that puts both into practice.

Each entry in the deployments array passed to defineWorkflowConfig takes this shape.