sanity-plugin-github-deploy

A Sanity Studio plugin for triggering and monitoring GitHub Actions deployments directly from the studio.

Motivation

Sanity offers powerful live content features and cache invalidation for frameworks like Next.js and Astro in SSR mode. But sometimes you just want a fully static site served from a CDN — zero runtime, zero maintenance, maximum performance.

In that setup, content changes don't go live until you rebuild and redeploy the site. This plugin gives editors a "Deploy" tab right inside Sanity Studio so they can trigger a full rebuild, deploy, and cache purge with a single click — no need to open GitHub or understand CI/CD.

How It Works

The plugin uses Sanity documents and webhooks — no secrets are needed in the Studio.

• Triggering a deploy: The Studio writes a deploy.trigger document. A Sanity webhook fires and notifies the deploy proxy, which dispatches the GitHub Actions workflow.
• Tracking status: GitHub sends workflow_run webhook events to the deploy proxy, which writes deploy.run documents back to Sanity. The Studio reads these via GROQ.

Trigger:  Studio ─── deploy.trigger doc ──▶ Sanity ─── webhook ──▶ Proxy ─── dispatch ──▶ GitHub
Status:   GitHub ─── workflow_run ─────────▶ Proxy ──── mutate ──▶ Sanity (deploy.run docs)
Read:     Studio ─── GROQ query ───────────▶ Sanity API (native auth)

Preparation

Before using this plugin, you need:

1. A GitHub Actions workflow in your repository that handles the full deploy pipeline (build, upload, cache purge). The workflow needs a workflow_dispatch trigger.
2. A deploy proxy that receives webhooks from both Sanity and GitHub. See Deploy Proxy Setup below.
3. A Sanity webhook configured in manage.sanity.io to notify the proxy when a deploy is triggered.
4. A GitHub webhook configured in your repository settings to notify the proxy of workflow run events.

Features

• Display of current live deployment
• List of changed content (documents) since last live deployment
• Button to trigger a new deployment with progress indicator

All content up to date

Undeployed changes

Deployment in progress

Installation

npm install sanity-plugin-github-deploy

Usage

Add the plugin to your sanity.config.ts:

import {defineConfig} from 'sanity'
import {deployTool} from 'sanity-plugin-github-deploy'

export default defineConfig({
  // ...
  plugins: [
    deployTool({
      // Optional: track undeployed changes for specific document types
      documentTypes: ['page', 'post', 'settings'],
      // Optional: GROQ expression for display title
      titleField: 'coalesce(title, name, _type)',
    }),
  ],
})

The plugin registers two document types automatically: deploy.trigger and deploy.run. No additional schema setup is needed.

Configuration

DeployToolOptions

| Option | Type | Required | Description | |--------|------|----------|-------------| | documentTypes | string[] | No | Document types to track for undeployed changes. Omit to disable. | | titleField | string | No | GROQ expression for the title projection. Default: coalesce(title, name, _type) |

Deploy Proxy Setup

The deploy proxy is a small server or edge function that receives webhooks from Sanity and GitHub. A reference implementation for Bunny CDN Edge Scripting is included in edge/deploy-proxy.ts.

Proxy Environment Variables

| Variable | Description | |----------|-------------| | GITHUB_TOKEN | GitHub personal access token with actions scope | | GITHUB_WEBHOOK_SECRET | Secret for validating GitHub webhook signatures | | SANITY_WEBHOOK_SECRET | Secret for validating Sanity webhook calls | | SANITY_TOKEN | Sanity API token with write access (for writing deploy.run documents) | | PROJECTS | JSON string mapping repository full names to project config (see below) |

PROJECTS Configuration

{
  "your-org/your-repo": {
    "workflowId": "deploy.yml",
    "branch": "main",
    "sanityProjectId": "abc123",
    "dataset": "production"
  }
}

Proxy Endpoints

| Method | Path | Description | |--------|------|-------------| | POST | /sanity-webhook | Receives Sanity webhook when deploy.trigger is created/updated, dispatches GitHub workflow | | POST | /github-webhook | Receives GitHub workflow_run events, writes deploy.run documents to Sanity |

Webhook Setup

Sanity Webhook (manage.sanity.io → API → Webhooks)

| Setting | Value | |---------|-------| | URL | https://your-deploy-proxy.example.com/sanity-webhook | | Secret | Must match SANITY_WEBHOOK_SECRET env var | | Filter | _type == "deploy.trigger" | | Trigger on | Create, Update |

GitHub Webhook (Repository → Settings → Webhooks)

| Setting | Value | |---------|-------| | Payload URL | https://your-deploy-proxy.example.com/github-webhook | | Content type | application/json | | Secret | Must match GITHUB_WEBHOOK_SECRET env var | | Events | Workflow runs |

License

MIT