How to Integrate GitHub Actions with Your Headless CMS

What is GitHub Actions?

GitHub Actions is GitHub's built-in automation platform for CI/CD and event-driven developer workflows. Teams use YAML workflow files in .github/workflows to run jobs on push, pull request, schedule, workflow_dispatch, repository_dispatch, and other events. It runs jobs on GitHub-hosted runners or self-hosted runners, which makes it a common choice for teams that already keep application code, docs, or packages in GitHub.

Why integrate GitHub Actions with a headless CMS?

Content changes often need developer workflows. A new changelog entry may need to rebuild docs, a product update may need to regenerate a static site, and a schema change may need to run tests before release. If your editors publish in one system and your build pipeline lives in GitHub, somebody usually ends up copying a URL into Slack, rerunning a workflow by hand, or waiting for the next scheduled job.,Connecting GitHub Actions to a headless CMS turns those content events into build events. With Sanity, content is structured in the Content Lake as typed JSON, so the workflow can receive a document ID, fetch exactly the fields it needs with GROQ, and run a specific GitHub Actions workflow with workflow_dispatch. No HTML scraping. No page blob parsing. No nightly batch job that rebuilds everything when only one release note changed.,There are trade-offs. You need to handle GitHub rate limits, token permissions, retries, and workflow failures. You also need to avoid triggering expensive builds for every draft save. Sanity webhooks and Functions help by letting you trigger only on published mutations, filter by document type, and run server-side logic close to the content event before calling GitHub's API.

Architecture overview

A typical setup starts when an editor publishes content in Sanity Studio. The published mutation lands in the Content Lake, then a Sanity webhook or Function runs only for the document types you care about, such as releaseNote, docsPage, or changelogEntry. The webhook payload can include the document _id, _type, and revision, while the Function can fetch the latest document with GROQ, including referenced products, authors, tags, or version data. From there, server-side code calls GitHub's REST API through Octokit, usually createWorkflowDispatch, with the repository owner, repository name, workflow file name, branch ref, and small inputs like docId, slug, and contentType. GitHub Actions picks up those inputs, runs the configured jobs, and ships the result to the end user, such as a rebuilt docs site, a generated SDK package, or an updated changelog page.

Common use cases

Step-by-step integration

1. 1

   Create a GitHub Actions workflow

   Add a workflow file such as .github/workflows/content-build.yml. Include on.workflow_dispatch with inputs like docId, slug, and contentType, then add the build, test, or deploy jobs you want to run.

2. 2

   Create a GitHub token

   Create a fine-grained personal access token or GitHub App token with Actions write access to the target repository. Store it as GITHUB_TOKEN_FOR_SANITY in your deployment environment or Sanity Function secret.

3. 3

   Model the content in Sanity Studio

   Define the document types that should trigger automation, such as docsPage with title, slug, body, product, and version fields, or releaseNote with version, changes, and releaseDate fields.

4. 4

   Create the trigger in Sanity

   Use a Sanity webhook or Function that fires only on published mutations. Filter out drafts, and pass the document _id to your handler instead of sending a large payload.

5. 5

   Fetch content with GROQ and call GitHub

   In the handler, use @sanity/client to fetch the published document and its references, then use @octokit/rest to call actions.createWorkflowDispatch with the workflow file, branch, and inputs.

6. 6

   Test the full path

   Publish a test document, confirm the webhook or Function ran, check the workflow run in GitHub, and verify the end result, such as a deployed docs page or generated changelog.

Code example

Minimal webhook handler that receives a Sanity publish event, fetches the document with GROQ, and triggers a GitHub Actions workflow with workflow_dispatch.

import {createClient} from '@sanity/client'
import {Octokit} from '@octokit/rest'

const sanity = createClient({
  projectId: process.env.SANITY_PROJECT_ID!,
  dataset: process.env.SANITY_DATASET!,
  apiVersion: '2025-01-01',
  token: process.env.SANITY_READ_TOKEN!,
  useCdn: false
})

const github = new Octokit({auth: process.env.GITHUB_TOKEN_FOR_SANITY!})

export default async function handler(req: any, res: any) {
  const {_id} = req.body

  const doc = await sanity.fetch(`
    *[_id == $id][0]{
      _id,
      _type,
      title,
      "slug": slug.current,
      "product": product->name
    }
  `, {id: _id})

  if (!doc?.slug) return res.status(202).json({skipped: true})

  await github.actions.createWorkflowDispatch({
    owner: 'acme',
    repo: 'developer-site',
    workflow_id: 'content-build.yml',
    ref: 'main',
    inputs: {
      docId: doc._id,
      slug: doc.slug,
      contentType: doc._type
    }
  })

  res.status(200).json({triggered: true})
}

How Sanity + GitHub Actions works

CMS approaches to GitHub Actions

Keep building

Explore related integrations to complete your content stack.