How to deploy Sanity with Github Actions

If you’ve ever pushed a small update to Sanity Studio only to realize you still need to manually deploy it, you know how frustrating it gets.

That’s where deploy Sanity with GitHub Actions and GitHub Actions for CMS come to the rescue. By automating your Sanity Studio deployments, these tools save time, reduce errors, and ensure your content updates go live seamlessly.

With this setup, you can streamline your development workflow, focus on building features, and let GitHub Actions handle the repetitive deployment tasks like making your CI/CD process more efficient than ever.

GitHub Actions for faster, smoother deployment

Github Actions is a robust CI/CD (Continuous Integration/Continuous Deployment) tool offered by Github that enables developers to automate workflows and tasks, reducing manual effort and ensuring consistent, error-free deployments. With GitHub Actions, one can define custom workflows using YAML files and trigger them based on specific events, such as code commits, pull requests, or scheduled intervals.

At the same time, Sanity CMS is a flexible and customizable headless content management system that allows developers to create structured content for their applications. It offers a real-time collaborative editing environment and a robust content API, making it an ideal choice for projects of all sizes.

And with the latest updates from Sanity and GitHub, deploying your Studio is smoother and safer than ever.

Why use GitHub Actions for Sanity CMS deployment?

Manual deployments eat up time and increase the chance of errors. By combining the capabilities of GitHub Actions with Sanity CMS, developers can automate the deployment of Sanity projects in lesser time with no errors. Deploying Sanity with GitHub Actions allows for efficient collaboration, seamless deployments, and improved development workflows. With GitHub Actions for Sanity CMS deployment, you can focus on writing code and delivering value, while the deployment process takes care of itself.

Automating with GitHub Actions ensures:

Configuring workflow triggers

In the workflow file, it's paramount to define the triggers that will initiate the deployment process. GitHub Actions provides several event types that can trigger workflows, such as push events, pull requests, and scheduled intervals.

Here’s an example of how you can configure a workflow to trigger on a push to the ‘main’ branch:

Yaml

name: Deploy sanity studio

on:

push:

branches: [main]

In this e.g., the workflow runs whenever a push occurs on the ‘main’ branch. You can customize the triggers as per your needs.

Getting started with Github Actions

Now that you know how triggers work, let’s create the actual workflow file in your repository. This file defines the steps GitHub Actions will run whenever your chosen event (like a push to ‘main’) occurs.

Setting up a Github repository

Before utilizing GitHub Actions for CMS, you need a repository on GitHub (if you already have one, skip this step). Otherwise:

1. Log in to your GitHub account and navigate to the main page.
2. Click “New” near the top-left corner.
3. Provide a meaningful repository name and description (optional).
4. Choose public or private, depending on your needs.
5. Select “Initialize” with a “README” (it's optional but recommended).
6. Click “Create repository”.

Creating a workflow file

Once you’ve created your repository, create a workflow file to define the deployment process. The workflow tells GitHub Actions what to do when specific events (like a push to ‘main’) occur. Follow these steps:

1. In your repository, go to the “Actions” tab.
2. Click “Set up a workflow yourself”, or pick a template.
3. Name your workflow file (e.g., deploy-sanity.yml).
4. Make sure it ends with .yml (YAML syntax).
5. Open the file in your editor and add the workflow instructions (we’ll show you an updated example in the next section).

Know more from GitHub Actions workflow tutorial.

Configuring Sanity for deployment

Before deploying with GitHub Actions for CMS, make sure you have a few essentials ready:

1. Sanity project: Either create a new project or use an existing one. For a quick start, check out our Working with Turbo Start Sanity guide to bootstrap your project in minutes. Make sure your schema is defined. Read Sanity CMS deployment guide
2. API token: Generate a token with ‘Deploy Studio’ permissions and add it to your GitHub repository secrets as SANITY_AUTH_TOKEN.
3. Add CI Specific secrets like
   1. SANITY_STUDIO_PROJECT_ID
   2. SANITY_STUDIO_DATASET
   3. SANITY_STUDIO_TITLE
   4. SANITY_STUDIO_PRESENTATION_URL
4. Deployment provider: Decide where your Studio will live Vercel, Netlify, AWS Amplify, or another provider. For insights on Sanity and Next.js integration best practices, check out our comprehensive takeaways from real-world projects.

Once that’s in place, here’s an updated workflow example using the latest Sanity GitHub Action:

Yaml
name: Deploy Sanity Studio
on:
  push:
    paths:
      - "apps/studio/**"
      - ".github/workflows/deploy-sanity.yml"
  workflow_dispatch:

permissions:
  contents: read
  id-token: write

jobs:
  deploy:
    name: Build and Deploy Sanity Studio
    runs-on: ubuntu-latest
    timeout-minutes: 15
    env:
      SANITY_AUTH_TOKEN: ${{ secrets.SANITY_AUTH_TOKEN }}
      NODE_OPTIONS: "--max_old_space_size=4096"
      PNPM_VERSION: 10.12.2
      SANITY_STUDIO_PROJECT_ID: ${{ secrets.SANITY_STUDIO_PROJECT_ID }}
      SANITY_STUDIO_DATASET: ${{ secrets.SANITY_STUDIO_DATASET }}
      SANITY_STUDIO_TITLE: ${{ secrets.SANITY_STUDIO_TITLE }}
      SANITY_STUDIO_PRESENTATION_URL: ${{ secrets.SANITY_STUDIO_PRESENTATION_URL }}
      HOST_NAME: ${{ github.head_ref || github.ref_name }}  

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Install pnpm
        uses: pnpm/action-setup@v2
        with:
          version: ${{ env.PNPM_VERSION }}
          run_install: false

      - name: Setup Node.js environment
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile --ignore-scripts --prefer-offline
        
      - name: Deploy Sanity Studio
        if: steps.check-dependabot.outputs.is_dependabot != 'true'
        working-directory: ./apps/studio
        run: |
          echo "Deploying Sanity Studio..."
          pnpm run deploy
        env:
          CI: true

This workflow:

• Uses the latest Sanity GitHub Action (v0.8-alpha)
• Supports custom studio paths for monorepos

What’s new in Sanity Studio?

Sanity Studio is now at v4.9.0 (2025). With v4, the CLI is more powerful, sanity.cli.ts config is flexible, at the same time, some old commands or flags no longer work.

To avoid frustrating “command not found” errors, always check your Studio version and update your workflows accordingly.

Security & Token Management

Security is critical in CI/CD. Here’s the safest way to handle it:

1. Create a “Deploy Token” inside Sanity
2. Store it in GitHub Secrets (Settings → Secrets → Actions) as SANITY_DEPLOY_TOKEN
3. Never hardcode tokens into your workflow file
4. For multiple environments (staging/prod), create separate tokens & datasets, and load them dynamically via secrets

Sanity now supports flexible sanity.cli.ts config, so you can pass environment-specific project IDs, datasets, and hosts cleanly.

Troubleshooting your deployment

Even with a smooth setup, issues can happen. Here are some common ones and quick tips to fix them:

1. Authentication errors: Check that your API tokens are correct and stored in GitHub secrets.
2. Build failures: Review logs for missing dependencies or syntax errors, and fix them in your project.
3. Deployment timeouts: Large projects may exceed workflow limits, optimize your build or adjust timeout settings.

GitHub Actions provides detailed logs to help you pinpoint problems and debug efficiently.

Best practices we’ve learned

Over time, here are a few things that has made our deployment easier:

1. Ignore clutter: Add .sanity to .gitignore
2. Monorepos made easy: Use studioPath or SANITY_STUDIO_CONFIG_PATH
3. Double check: Skim GitHub Action logs after each deploy, they catch 90% of issues early

Conclusion

The days of manually pushing Sanity Studio builds are gone. Github Action for Sanity CMS deployment empowers developers to streamline their workflow by automating the deployment process of Sanity projects. By leveraging Github Actions and the flexibility of Sanity CMS, you can save time, improve collaboration, and ensure consistent, error-free deployments.

All thanks to recent updates: config flexibility, safer token handling, and a streamlined workflow that has made deployment process faster and more reliable than ever.

Start implementing Github Actions in your Sanity projects and experience the benefits of automated deployments.