How to Integrate GitHub with Your Headless CMS

What is GitHub?

GitHub is a developer platform for Git repositories, code review, issues, pull requests, GitHub Actions, packages, and security workflows. It’s used by individual developers, open-source projects, and companies to collaborate on software and automate delivery. Its core capability is version-controlled collaboration around code and related project assets.

Why integrate GitHub with a headless CMS?

Developer tools teams often split content across two places. Product marketers and docs writers work in an editorial interface, while engineers keep examples, docs sites, changelogs, and release notes in GitHub. Without an integration, someone copies Markdown into a repo, opens a pull request by hand, waits for review, and hopes the deployed docs match what was approved.

Architecture overview

A typical Sanity and GitHub integration starts when an editor publishes a document in Sanity Studio. A webhook with a GROQ filter, for example _type == "docPage" && defined(slug.current), fires only for the document types you want to sync. The webhook sends the document ID to a Sanity Function or your own small API route. That server-side code uses @sanity/client to fetch exactly the fields GitHub needs from the Content Lake with GROQ, including referenced authors, product areas, and release versions. Then it calls GitHub’s REST API through @octokit/rest, commonly PUT /repos/{owner}/{repo}/contents/{path}, to create or update a Markdown, MDX, or JSON file in a repository. If you use protected branches, the same code can commit to a content-sync branch and open a pull request with POST /repos/{owner}/{repo}/pulls. From there, GitHub Actions can build the developer portal, run lint checks, publish a static site, or notify reviewers. The end user sees updated docs, release notes, or API references after the GitHub workflow passes and deploys.

Common use cases

Step-by-step integration

1. 1

   Set up GitHub access

   Create a GitHub repository for the synced content, or choose an existing docs or developer portal repo. For a simple test, create a fine-grained personal access token with Contents read and write access for that repo. For production, use a GitHub App with repository permissions for Contents, Pull requests, and Issues, then store the token or app credentials as environment variables.

2. 2

   Install the GitHub and Sanity SDKs

   In your Sanity Function, webhook listener, or middleware project, install @octokit/rest and @sanity/client. You’ll use @sanity/client to read structured content from the Content Lake and Octokit to call GitHub’s REST API.

3. 3

   Model the content in Sanity Studio

   Create schemas for the content you want to sync, such as docPage, changelogEntry, apiReference, or exampleProject. Include fields that map cleanly to GitHub files, for example title, slug, body, version, productArea, authors, status, and githubPath.

4. 4

   Create the publish trigger

   Add a Sanity webhook with a GROQ filter such as _type == "docPage" && defined(githubPath). Send a small payload, for example {_id, _type}, to a Sanity Function or webhook endpoint. If you need retries, secrets, and no separate server, use Functions for the sync logic.

5. 5

   Write to GitHub

   Fetch the full document with GROQ, render the fields into Markdown, MDX, or JSON, then call GitHub’s createOrUpdateFileContents API. For protected branches, write to a sync branch and open a pull request instead of committing to main.

6. 6

   Test the frontend workflow

   Publish a test document, confirm the commit or pull request appears in GitHub, and run the related GitHub Actions workflow. Check the deployed docs page, verify links, and test update and delete behavior before turning the integration on for production content.

How Sanity + GitHub works

CMS approaches to GitHub

Keep building

Explore related integrations to complete your content stack.