How to Integrate Linear with Your Headless CMS

What is Linear?

Linear is an issue tracking and product development tool for software teams. Teams use it to plan cycles, track projects, triage bugs, and coordinate engineering work through issues, labels, views, and projects. It is widely used by product and engineering teams at SaaS and developer tools companies that need a fast workflow and a GraphQL API.

Why integrate Linear with a headless CMS?

Developer tools teams often publish content that should create engineering follow-up: a docs page needs review after an API change, a changelog entry needs QA, or a roadmap page needs tasks for launch. If Linear and your headless CMS are disconnected, someone has to copy titles, URLs, owners, and context into an issue by hand. That’s slow, and it usually drops the details engineers need.,A headless CMS category tool helps because content is already separated from presentation. With Sanity’s AI Content Operating System, that content is structured as typed JSON in the Content Lake, so a webhook can send exactly the document ID that changed, a GROQ query can fetch the fields Linear needs, and a Function or webhook listener can call Linear’s API in seconds.,The trade-off is that you need to decide what should create an issue and what should not. Syncing every edit will create noise. A better pattern is to trigger only on publish, only for specific document types, and only when fields like status, release, or requiresEngineeringReview match your workflow.

Architecture overview

A typical Linear integration starts when an editor publishes a document in Sanity Studio, such as a changelog entry, API reference page, or launch note. A Sanity webhook fires on that publish event and sends a small payload, often just the document ID, to a webhook listener. If you don’t want to run that listener yourself, the same logic can run in a Sanity Function, which executes server-side code on content mutations without a separate worker. The listener uses @sanity/client to fetch the published document from the Content Lake with GROQ. The query selects only the fields Linear needs, such as title, summary, slug, release version, owner, product area, Linear team ID, and label IDs. Then the listener calls Linear through @linear/sdk or Linear’s GraphQL API, usually with createIssue for a new task or issueUpdate for an existing one. The returned Linear issue ID and URL can be written back to the Sanity document so editors can see the engineering ticket from Sanity Studio. From there, the end user sees the result in the right place. Engineers work from the Linear issue, editors see the linked ticket in Sanity Studio, and the website or app can render the same content from Sanity without waiting on Linear. If you also display issue state, fetch it from Linear at build time, through middleware, or in a scheduled sync rather than on every page request.

Common use cases

Step-by-step integration

1. 1

   Set up Linear access

   Create a Linear workspace and team, then generate a personal API key from Linear settings under API. For production apps used by multiple workspaces, use Linear OAuth instead. Install the SDK with npm install @linear/sdk.

2. 2

   Model the Sanity content

   In Sanity Studio, add fields that make the sync predictable: title, slug, summary, publishStatus, requiresEngineeringReview, linearTeamId, linearLabelIds, linearIssueId, and linearIssueUrl. Keep Linear IDs as explicit fields so editors don’t have to guess where an issue will go.

3. 3

   Create the trigger

   Add a Sanity webhook that fires on publish for specific document types, such as changelogEntry or docsPage. Use a small projection like { "_id": _id } so the handler fetches the latest published content from the Content Lake instead of trusting a large webhook payload.

4. 4

   Fetch the exact fields with GROQ

   In your webhook listener or Sanity Function, use @sanity/client and GROQ to fetch only the fields Linear needs. Join references, such as owner, product area, or release, before you call Linear so the issue description contains useful context.

5. 5

   Create or update the Linear issue

   Use @linear/sdk to call createIssue with teamId, title, description, and labelIds. If the Sanity document already has linearIssueId, call issueUpdate instead of creating a duplicate.

6. 6

   Test the full loop

   Publish a test document, confirm that Linear receives one issue with the right team and labels, then write the Linear issue URL back to Sanity. Add signature verification, retries, and duplicate checks before using it for production content.

How Sanity + Linear works

CMS approaches to Linear

Keep building

Explore related integrations to complete your content stack.