Deploy Blueprints with GitHub Actions

Use the official Blueprints actions to plan and deploy your Blueprints with GitHub Actions.

The official Blueprints GitHub Actions let you add Blueprint planning and deployment to your existing GitHub workflows.

Before you get started, have a local Blueprint configured and committed to the git repository you want to use. If you’re new to Blueprints, you can get started by creating a function.

Before using these actions, you need configuration values from your project. Run the following command to retrieve your project and stack IDs:

npx sanity@latest blueprints config

Current configuration:
  Deployment: Stack <stack_id>
   Scoped to: Project <project_id>
     Updated: <timestamp>
        File: ./.sanity/blueprint.config.json

Next, you’ll need a Sanity API token with permission to deploy the Blueprint. The recommended way to create one is with the CLI. In your project directory, run:

npx sanity@latest blueprints mint-deploy-token --print

pnpm dlx sanity@latest blueprints mint-deploy-token --print

yarn dlx sanity@latest blueprints mint-deploy-token --print

bunx sanity@latest blueprints mint-deploy-token --print

The command creates a robot token with the role required to plan, deploy, and destroy Blueprints in your Blueprint’s scope: blueprints-deployer for a project-scoped Blueprint, or blueprints-deployer-robot for an organization-scoped one. The --print flag prints only the raw token, so copy it from your terminal. Minting a token requires project admin access for a project-scoped Blueprint, or organization admin access for an organization-scoped one.

To create the token in the Sanity Manage UI instead, follow these steps:

• Go to sanity.io/manage.
• Select your project or organization. Organization-scoped Blueprints require an organization-level token.
• Go to API > Tokens.
• Select Add API token.
• Create a token with the Blueprints Deployer permission.
• Copy the token (you won't be able to see it again).

If you’re creating tokens programmatically, you’ll need the following permissions:

• Project-scoped: sanity.project.blueprints.deploy
• Organization-scoped: sanity.blueprints.deploy

Next, add the API token to your GitHub secrets.

• Go to your GitHub repository.
• Navigate to Settings > Secrets and variables > Actions.
• Select New repository secret.
• Name: SANITY_TOKEN.
• Value: Paste your Sanity API token.
• Select Add secret.

There are two actions available: deploy and plan.

The Deploy action executes sanity blueprints deploy in your GitHub workflow, automatically applying your Blueprint configuration to your Sanity project. It deploys your resources, like functions, and provides a deployment status output for use in your workflow.

Some ways you can use it are:

• On pushes to your main/production branch for continuous deployment.
• As part of a release workflow.
• For scheduled deployments.
• After manual workflow dispatch.

The Plan action runs sanity blueprints plan and automatically posts the results as a PR comment, giving your team visibility into what changes will be applied. It shows specific changes in the resources, as well as a summary of all changes.

Some ways you can use it are:

• Confirm what a Blueprint will do before deploying.
• Automatically post results as a collapsible PR comment.
• Keep your PR discussions clean and organized.

Create .github/workflows/deploy-blueprints.yml. Replace the stack and project ID placeholders with your values.

name: Deploy Sanity Blueprints

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5

      - name: Install dependencies
        run: npm ci  # or pnpm/yarn

      - name: Deploy blueprints
        uses: sanity-io/blueprints-actions/deploy@deploy-v3
        with:
          sanity-token: ${{ secrets.SANITY_TOKEN }}
          stack-id: 'ST_1234xyz'
          project-id: '1234xyz'
          # organization-id: '1234xyz' # if you're deploying an org-scoped blueprint

Create .github/workflows/plan-blueprints.yml. Replace the stack and project ID placeholders with your values.

name: Sanity Blueprints Plan

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write  # Required for posting comments

jobs:
  plan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5

      - name: Install dependencies
        run: npm ci  # or pnpm/yarn

      - name: Plan blueprints changes
        uses: sanity-io/blueprints-actions/plan@plan-v2
        with:
          sanity-token: ${{ secrets.SANITY_TOKEN }}
          stack-id: 'ST_1234xyz'
          project-id: '1234xyz'
          # organization-id: '1234xyz' # if you're planning an org-scoped blueprint

If your Blueprint isn’t at the root of your repository, add working-directory.

name: Sanity Blueprints Plan

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write  # Required for posting comments

jobs:
  plan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5

      - name: Install dependencies
        run: npm ci  # or pnpm/yarn

      - name: Plan blueprints changes
        uses: sanity-io/blueprints-actions/plan@plan-v2
        with:
          sanity-token: ${{ secrets.SANITY_TOKEN }}
          stack-id: 'ST_1234xyz'
          project-id: '1234xyz'
          working-directory: 'path/to/blueprints'

The deploy action logs the deployment progress and provides a deployment-status output you can use in subsequent workflow steps. For example:

- name: Deploy blueprints
  id: deploy
  uses: sanity-io/blueprints-actions/deploy@deploy-v3
  with:
    sanity-token: ${{ secrets.SANITY_TOKEN }}
    stack-id: 'ST_1234xyz'
    project-id: '1234xyz'

- name: Notify on success
  if: steps.deploy.outputs.deployment-status == 'success'
  run: echo "Deployment successful!"

If the action fails with Missing either a `project-id` or an `organization-id`., it received neither input. Set project-id for a project-scoped Blueprint, or organization-id for an organization-scoped one. If the value comes from a secret or variable, check that it isn’t empty.

The Plan action needs the pull-requests: write permission to create or update its pull request comment. Add it under the top-level permissions key of your workflow file.

When a project ID is set, the CLI uses the project scope, even if an organization ID is also set. For an organization-scoped Blueprint, set organization-id and remove project-id. The token must match the scope too. A project-scoped token can’t deploy an organization-scoped stack, including a stack you promoted to organization scope. Mint an organization-scoped token and update the SANITY_TOKEN secret:

npx sanity@latest blueprints mint-deploy-token --organization-id YOUR_ORGANIZATION_ID --print

pnpm dlx sanity@latest blueprints mint-deploy-token --organization-id YOUR_ORGANIZATION_ID --print

yarn dlx sanity@latest blueprints mint-deploy-token --organization-id YOUR_ORGANIZATION_ID --print

bunx sanity@latest blueprints mint-deploy-token --organization-id YOUR_ORGANIZATION_ID --print

Visit the GitHub Actions repository for additional details.

• To deploy from a CI system other than GitHub Actions, see Deploy Blueprints from CI.
• To deploy one Blueprint to separate staging and production stacks, see Manage environments with Blueprints.
• To learn what happens when a deploy fails, see Errors and rollbacks.