How to Integrate CircleCI with Your Headless CMS

What is CircleCI?

CircleCI is a continuous integration and delivery platform that runs builds, tests, security checks, and deployments from code repositories hosted on GitHub, GitLab, and other Git providers. Engineering teams use it to define repeatable pipelines in .circleci/config.yml, pass pipeline parameters, and ship changes through controlled workflows. It’s widely used by product engineering, platform, DevOps, and developer relations teams that need predictable automation after code or content changes.

Why integrate CircleCI with a headless CMS?

Developer-facing content often ships like code. A docs page changes, an API reference updates, a changelog entry goes live, or a tutorial gets a new code sample. If that content feeds a static site, developer portal, SDK docs site, or internal enablement app, you probably need CircleCI to rebuild, run link checks, generate search indexes, and deploy the result.

Without an integration, someone copies a URL into Slack, asks an engineer to rerun a workflow, or waits for a nightly rebuild. That’s slow, and it’s easy to miss small but important changes. A connected workflow turns a publish event into a CircleCI pipeline with context, such as the document ID, content type, locale, affected route, or release channel.

A headless CMS with structured content and real-time events makes this cleaner because the pipeline doesn’t need to scrape rendered HTML or guess what changed. With Sanity’s AI Content Operating System, content lives as typed JSON in the Content Lake, webhooks can fire on publish events, GROQ can fetch only the fields CircleCI needs, and Functions can run server-side trigger logic without another service to host.

Architecture overview

A typical Sanity and CircleCI integration starts when an editor publishes or updates content in Sanity Studio. A GROQ-powered webhook filters the event, for example, only _type == "docsPage" or _type == "changelogEntry", so routine draft edits don’t trigger builds. The webhook sends the mutation payload to a small handler or a Sanity Function. That handler uses @sanity/client to query the Content Lake with GROQ and fetch the fields needed by the pipeline, such as slug, title, locale, release tag, related product, and last published timestamp. If the content references other documents, GROQ can join them in the same query. The handler then calls CircleCI’s v2 API at POST /project/{project-slug}/pipeline with a CircleCI API token in the Circle-Token header. The request can pass pipeline parameters, such as content_id, content_type, content_slug, and rebuild_docs. CircleCI receives the pipeline, runs the configured workflow in .circleci/config.yml, and deploys the updated site, rebuilds search data, runs tests, or publishes artifacts. The end user sees the updated developer experience after the pipeline completes.

Common use cases

Step-by-step integration

1. 1

   Set up CircleCI for the target project

   Create or sign in to a CircleCI account, connect your GitHub or GitLab repository, and add a .circleci/config.yml file with a workflow that can build, test, and deploy your content site. In CircleCI, create a personal API token under User Settings, then store it as CIRCLECI_TOKEN in the environment where your webhook handler or Sanity Function runs.

2. 2

   Add pipeline parameters to .circleci/config.yml

   Define parameters such as content_id, content_type, content_slug, and rebuild_docs so the API trigger can tell CircleCI what changed. Your jobs can use those parameters to run targeted link checks, rebuild specific search records, or skip expensive work when the change doesn’t affect production pages.

3. 3

   Model the content in Sanity Studio

   Create schemas for the content that should trigger automation. For a developer portal, that might include docsPage with title, slug, product, locale, body, codeSamples, and status fields, plus changelogEntry with version, releaseDate, and affectedApis.

4. 4

   Create the event trigger

   Use a Sanity webhook with a GROQ filter like _type in ["docsPage", "changelogEntry"] && !(_id in path("drafts.**")) so only published content triggers CircleCI. Point the webhook to your API route, middleware, or Sanity Function endpoint.

5. 5

   Fetch the exact content and call CircleCI

   In the handler, use @sanity/client to query the Content Lake with GROQ, then call CircleCI’s v2 trigger pipeline endpoint. Use the project slug format vcs/org/repo, for example gh/acme/dev-portal, and send pipeline parameters in the JSON body.

6. 6

   Test the full publishing path

   Publish a test document in Sanity Studio, confirm the webhook delivery, check that CircleCI starts a pipeline, and verify that the deployed page or generated artifact reflects the updated content. Also test a draft edit to make sure it doesn’t trigger a production build.

How Sanity + CircleCI works

CMS approaches to CircleCI

Keep building

Explore related integrations to complete your content stack.