Promote a stack to organization scope

Learn how to promote an existing project-scoped blueprint stack to organization scope to unlock scheduled functions.

Every blueprint stack has a scope that determines which resource types it can manage. By default, stacks are scoped to a project. To deploy organization-level resources like scheduled functions, you need to promote the stack to organization scope.

Scheduled functions (sanity.function.cron) run on a timer rather than responding to document changes in a specific project. Because they operate independently of any single project, they require organization scope.

If you add a scheduled function to a project-scoped stack and run sanity blueprints deploy, the deployment will fail with an error indicating that the resource requires organization scope. Promoting your stack resolves this.

• An existing project-scoped blueprint stack. If you have not initialized a blueprint yet, see the Blueprints introduction or one of the Blueprint or Function guides.
• A role (such as Administrator) with the sanity.organization.update permission on the organization that owns the project. Project-level permissions alone are not sufficient.
• The project must belong to an organization. Standalone projects cannot be promoted.
• No active deployments or operations running on the stack.
• Deploying an organization-scoped blueprint requires an organization admin role, or a robot token with the sanity.blueprints.deploy permission.

Before promoting, confirm that your stack is currently project-scoped by running the config command:

npx sanity@latest blueprints config

pnpm dlx sanity@latest blueprints config

yarn dlx sanity@latest blueprints config

bunx sanity@latest blueprints config

If the output shows Scoped to: Project <id>, the stack is project-scoped and eligible for promotion.

Run the promote command from a directory containing your configured blueprint:

npx sanity@latest blueprints promote

pnpm dlx sanity@latest blueprints promote

yarn dlx sanity@latest blueprints promote

bunx sanity@latest blueprints promote

The CLI will ask you to confirm the promotion. After confirming, the command performs a single atomic operation that:

• Changes the stack's scope from project to organization.
• Sets a value on the stack to preserve the original project ID so your existing project-scoped resources continue to work. You can also explicitly set the project for each resource, but this keeps your existing resources working as expected.
• Updates your local .sanity/blueprint.config.json by removing projectId and adding organizationId.

You can optionally pass the --force flag to skip the confirmation prompt, or --stack <name-or-id> to target a specific stack if you have more than one.

After promotion, confirm the scope change by running the config command again:

npx sanity@latest blueprints config

pnpm dlx sanity@latest blueprints config

yarn dlx sanity@latest blueprints config

bunx sanity@latest blueprints config

The output should now show Scoped to: Organization <id>. You can also check sanity blueprints logs to see the promotion operation recorded in the stack's history.

With the stack promoted, you can now define both project-scoped and organization-scoped resources in the same blueprint:

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

export default defineBlueprint({
  resources: [
    // Existing project-scoped resource, still works via defaultProjectId
    defineDocumentFunction({
      name: 'on-publish',
      event: {on: ['create', 'update']},
      // Or, explicitly set the project resource:
      project: `<your-project-id>`
    }),

    // New org-scoped resource, enabled by promotion
    defineScheduledFunction({
      name: 'daily-digest',
      event: {expression: '0 9 * * *'}, // you can also use the day, minute, hour, year syntax
    }),
  ],
})

When you run sanity blueprints deploy, the scope resolver handles each resource appropriately. Project-scoped resources like document functions resolve through project, while organization-scoped resources like scheduled functions use the organization scope directly. See each definer’s reference documentation for further configuration details.

There is no command to demote a stack back to project scope. Organization scope is strictly broader than project scope, so an org-scoped stack can do everything a project-scoped stack can. If you promote by mistake, your existing resources continue working exactly as before.

The promote command automatically updates your .sanity/blueprint.config.json file. If your CI/CD pipeline reads from this file, no pipeline changes are needed. However, if your pipeline sets SANITY_PROJECT_ID as an environment variable, switch to SANITY_ORGANIZATION_ID after promotion.

After promotion, the stack is updated with details from the original project. To target resources in a different project, add an explicit project attribute to individual resource definitions. This allows a single org-scoped stack to manage resources across multiple projects.

Stacks are limited to 3 per scope. After promotion, the stack belongs to the organization and is no longer counted against the project's stack limit. Stack names must be unique within a scope. If the organization already has a stack with the same name, the promotion will fail.

Promotion requires the sanity.organization.update permission. If you receive a 403 error, ask an organization administrator to grant you the required permission.

You cannot promote a stack while a deployment or other operation is active. Wait for the current operation to complete, then retry the promote command.

Stack names must be unique within a scope. If the organization already has a stack with the same name, promotion fails with a DuplicateStackNameError. To resolve this, destroy and recreate one of the stacks with a different name.

The promote command is idempotent. Running it on an already-promoted stack returns success without making any changes. You can safely retry the command if you are unsure whether a previous promotion completed.