Building a PR-like content workflow in Hygraph

If you've ever worked with Git, you know the power of pull requests: propose changes, get feedback, iterate, and only merge when approved. But what about content? Marketing teams, documentation writers, and editorial staff need the same collaborative review process.

Here's how to build exactly that in Hygraph using Workflows and a simple Review component.

#The problem

Your content team faces a familiar challenge:

• Authors want to edit documents without breaking what's live
• Reviewers need to see proposed changes before they go public
• Everyone wants a clear trail of who approved what

#The solution: Workflow steps as PR stages

Hygraph Workflows let you define steps that content must pass through before publishing. Think of each step as a PR status: Draft → Open → Under Review → Merged.

Here's what a real implementation looks like:

The four stages

The magic is in the configuration:

• "Can be returned to" enables the rejection flow—send content back for revisions
• "Publish to Published when moved to this step" auto-publishes approved content
• Role restrictions ensure only the right people can approve

#Adding review comments

Workflows handle the flow, but what about the feedback? You need a place for reviewers to leave notes.

The simplest solution: a Review component with two fields:

Review (repeatable component)
├── review notes (Rich Text) — The feedback itself
└── person (Relation to Person/User) — Who left the review

This gives you:

• Threaded feedback: Each review is a separate entry, showing reviewer and timestamp
• Rich formatting: Reviewers can use bold, lists, links in their notes
• Attribution: Clear record of who said what
• History: Reviews persist even after content is published

Why a component instead of a field?

A single reviewNotes text field works, but a repeatable component is better because:

1. Multiple reviewers can leave separate notes (not overwrite each other)
2. Each note is timestamped and attributed
3. You can query reviews independently via the API
4. Reviews can be cleared after publishing without losing the content history

#Extending the pattern

Once you have the basic PR workflow, consider these enhancements:

1. Webhook notifications

Trigger Slack/Teams/Email notifications on stage transitions:

When: Content moves to "Pull request open"
Action: POST to webhook → "New content ready for review: {title}"

2. Due dates

Add a reviewDeadline date field to the Review component. Query for overdue reviews:

query OverdueReviews {
  documents(where: { 
    workflow: { step: "pullRequestOpen" },
    reviewDeadline_lt: "2026-02-04"
  }) {
    title
    reviews { person { name } }
  }
}

3. Diff preview

Build a simple frontend (or even a custom app) that queries both DRAFT and PUBLISHED stages and shows a side-by-side comparison. Libraries like diff or jsdiff make this straightforward.

#Why this matters

Content teams often inherit developer tools (Google Docs comments, Notion, etc.) that weren't built for structured content. Or they skip review entirely because it's too cumbersome.

Hygraph Workflows give you:

• Structured review that lives with your content model
• Role-based gates enforced by the system, not by convention
• Audit trail of who approved what, when
• API access to review status for custom dashboards or automation

And because it's all native to Hygraph, there's no sync issues, no duplicate content, and no third-party tools to manage.

#Getting started

1. Enable Workflows in your project settings
2. Create the Review component (rich text + person relation)
3. Add the component to your document models
4. Configure workflow steps matching your team's review process
5. Assign roles to your team members

The implementation shown here took about 30 minutes to set up. The payoff—structured, auditable content review—lasts forever.

Have questions about implementing content workflows? Reach out to your Hygraph Solution Architect or check the Workflows documentation.