Blueprints: Organization-scoped blueprint stacks

Blueprint stacks now support organization scope.

Some resource types, starting with Scheduled Functions, exist only at the organization level and cannot be deployed from a project-scoped stack. Organization-scoped stacks reach across multiple projects from a single blueprint, so they grow with your Sanity footprint. Project-scoped stacks remain a fine default when your work focuses on a single project, or when you don't have org-level permissions.

Create a new organization-scoped stack

If you're starting fresh, use blueprints init rather than promoting. The new scope wizard asks which organization you're working in, whether to scope the new stack to that organization or to a single project, and, if you pick project scope, which project. Every choice is editable: back up to change an answer and the rest of the wizard updates to match.

Promote with one command

Promoting a stack lifts an existing stack from a single project to its parent organization, so one stack can manage resources that span projects (including the new Scheduled Functions) without disturbing any of the project-scoped resources you already deploy.

Run blueprints promote on an existing project-scoped stack. The CLI performs a single atomic operation that switches the scope, preserves the original project ID so existing resources keep resolving, and updates your local .sanity/blueprint.config.json file.

npx sanity@latest blueprints promote

Existing resources keep working

Promotion does not redeploy or rewrite anything that’s already deployed. Document functions, webhooks, CORS origins, and other project-scoped resources continue to work. The stack remembers its original project and resolves project-scoped resources against it.

Mix scopes in one blueprint

After promoting, the same blueprint can declare both project-scoped and organization-scoped resources side by side. Add an explicit project attribute on a resource to target a different project from the same stack.

import {
defineBlueprint,
defineDocumentFunction,
defineScheduledFunction,
} from '@sanity/blueprints'

export default defineBlueprint({
resources: [
// Project-scoped resource, resolves against the stack’s default project
defineDocumentFunction({
name: 'on-publish',
event: {on: ['create', 'update']},
}),

// Organization-scoped resource, enabled by promotion
defineScheduledFunction({
name: 'daily-digest',
event: {expression: '0 9 * * *'},
}),
],
})

Requirements

Administrator or the new Blueprints Deployer role on the organization the stack will live under. Project-level roles alone are not sufficient.

To promote a stack, its project must belong to an organization. Standalone projects cannot be promoted.

No active deployments or operations on the stack at the time of promotion.

Deploying an organization-scoped stack requires an organization admin or blueprints deployer role. Alternatively, use a Blueprints Deployer token, created from the organization’s Manage interface or with the blueprints mint-deploy-token command.

Promotion is one-way but risk-free. The command is also idempotent, so it’s always safe to retry. The promotion event will be listed in the logs for that stack; use the blueprints logs command to see your stack’s history.

Get started

Read Promote a stack to organization scope for a full walkthrough, or revisit the Blueprints introduction to learn how stacks fit into the bigger picture.