Content review similar to Git pull requests

[Gareth Budge]

Hi all,

What's the Atlassian recommended approach to instrument a review process for Confluence page (not Blogs) creation, updates and deletion?

It seems like in these forums the generally recommended approach is to get something from the Marketplace but given Confluence does have versioning, status labelling, etc. I am expected something a bit more out of the box.

Perhaps the way I am thinking of this is incorrect, but I would envisage something similar to a Git pull request. If the docs for an application were potentially versioned in the same repo as the application, any PR to change the application with/without any changes to the docs/ would attest whether or not any documentation updates were required.

Any guidance / feedback is greatly appreciated.

G

[Levente Szabo _Midori_]

@Gareth Budge I think your requirement is very valid but the way you think about it touches on at least 3 key areas of Confluence content management. There is no built-in way that would solve all these in good quality and probably can't even be expected.

Confluence Cloud has built-in "statuses", "versioning" but as soon as you start using those in real use cases, the limitations become clear (just think about the fact that it has 5 built-in statuses. No company can fit their workflows to just 5 statuses except for small teams with very simple needs.)

I think the areas you touch on are:

1. Confluence content review workflows - to automatically set page status in Confluence, notify and remind page owners that a review is due, and ultimately take automatic action (archiving/deletion)
2. Confluence content analysis and usage reporting - with the goal of better understanding content quality, overall site and space usage, and user activity, like a heatmap for your instance
3. Advanced page versioning - for clear comparisons and change tracking.

Advanced versioning and approval workflows have their dedicated apps, already mentioned.

For Confluence content lifecycle management and content review workflow, Better Content Archiving is the go-to tool. The on-premise version has been on the market for 15 years, helping teams at companies like PayPal, LinkedIn, and the like. The cloud version strives to deliver even more flexibility, features, and Confluence automation for all tiers.

Better Content Archiving also brings comprehensive Confluence analytics and reporting dashboards. It is comparable to the built-in Confluence Analytics, but with more data sources in one place, more focus on content lifecycle, and availability for all tiers, not just the high-end!

Start a free trial to take advantage:

(Please note that Better Content Archiving is a free/paid, supported app and I'm part of the team developing it.)

[Flowdence]

Hi @Gareth Budge ,

Your instinct to want something PR-like in Confluence is shared by a lot of teams — the idea that changes should be reviewed before they become the "live" version.

Confluence does have versioning built in, but the missing piece is binding an approval decision to a specific version. Right now, if someone approves a page and then another user edits it, the approval still shows as valid — there is no equivalent of a PR merge that locks in a reviewed snapshot.

The apps mentioned above handle workflow states well (draft, in review, approved). Where they differ is in how they treat versioning after approval. A few things worth asking when evaluating:

• Version-bound approvals — does the approval lock to the exact page version the reviewer saw? If the page is edited after approval, does the status automatically reflect that?
• Multi-step review — can you require sequential sign-offs (e.g., SME accuracy check, then manager tone review, then legal)?
• Audit export — can you pull a compliance-ready report showing who approved what version and when?

We built ApprovalFlow for Confluence around this exact gap — version-aware approvals where the status automatically goes stale when content changes, multi-step sequential review, and exportable audit trails. It runs on Forge (Atlassian-hosted, no external data transfer), and the workflow is closer to the PR mental model you described: submit a version for review, reviewers approve that specific version, edits after approval are clearly visible.

Happy to answer any questions.

Disclosure: I am from Flowdence, the team behind ApprovalFlow.

Thanks,

Team Flowdence

[david_patzer]

Hi @Flowdence 

Thank you for the detailed explanation of ApprovalFlow.

We're an AI-agent-driven documentation workflow and would love to understand how well ApprovalFlow can help. Here's the scenario:

1. An AI agent opens a GitHub pull request for a code or configuration change.
2. A linked documentation agent connects to Confluence via the Atlassian MCP, compares the existing documentation against the proposed PR changes, and identifies which pages need updating.
3. It then makes those documentation edits across multiple Confluence pages simultaneously — all of which are related to the same underlying change.
4. We want product people (not the AI) to review and approve those Confluence page changes before they go live.

A few specific questions this raises for ApprovalFlow:

- Can a single approval request span multiple pages at once, with the shared GitHub PR context visible to reviewers so they understand why all those pages changed together?
- Does ApprovalFlow support grouping related page changes into one review bundle — similar to how a PR groups multiple file changes?
- Can approvals be triggered programmatically (e.g., via API or automation) so the AI agent can initiate the review workflow after making its edits?
- Ownership of over 100 pages in a single space is shared among various product managers. How can we ensure that approval requests are routed to the correct individual?

Looking forward to your answers.

Best,
David

[Flowdence]

Hi @david_patzer 

Great questions — your workflow is exactly the kind of automation-native documentation pipeline we've been designing for. Let me address each one directly.

Can a single approval request span multiple pages, with the shared GitHub PR context visible to reviewers?

Yes. ApprovalFlow supports change sets — you can group related pages together under a shared title, description, and reference link (your GitHub PR URL). When pages in a change set are submitted for review, each Confluence page's footer comment shows the change set name, summary, and a clickable link back to the PR. Reviewers see why all those pages changed together without leaving Confluence.

Each page is still reviewed individually — we intentionally preserve per-page review because a security doc and an API reference often need different eyes. But the shared context makes the relationship between changes clear.

Does ApprovalFlow support grouping related page changes into one review bundle?

Yes — change sets are that bundle. You can view all pages in a change set together in the space dashboard, see a single rollup status (e.g., "In Review", "Partially Approved", "All Approved", "Stale"), and track per-page version data including which version was approved and whether the page has been edited since approval.

Can approvals be triggered programmatically?

Yes. ApprovalFlow exposes a full REST API through Forge's apiRoute module, secured with 3LO (OAuth 2.0). Your AI agent can:

1. Create a change set — POST /changeSets with the PR URL, affected page IDs, and a summary.
2. Preflight — POST /changeSets/preflight returns, per page, which workflow will be used, whether the page can be submitted, and if not, why (no workflow assigned, already in review, page deleted, etc.). This gives your agent a deterministic check before attempting submission.
3. Submit — POST /changeSets/submit submits all eligible pages. Pages that can't be submitted are skipped with specific reasons, and the response tells your agent exactly what happened.
4. Poll status — GET /changeSets/detail returns the rollup state and per-page version data so your agent knows when review is complete.

For individual pages, there's also POST /pages/preflight and POST /pages/submit.

All API actions use the authenticated user's real Atlassian identity from the OAuth token — audit trails, Confluence comments, and the page byline show who submitted (with a "(via API)" marker to distinguish automated from manual submissions). The OAuth client ID is stored in audit metadata for traceability.

How can we ensure approval requests are routed to the correct product manager for 100+ pages?

ApprovalFlow uses per-page workflow assignments. Each page can be assigned to a specific workflow (which defines who the approvers are for each review step). In the space dashboard's Manage Space view, admins can assign a workflow to a page and optionally apply it to all child pages underneath — so assigning "Security Review" to your /security parent page propagates to all its descendants.

For your 100+ pages, the setup workflow would be:

1. Organize your docs into logical parent pages by ownership area (Security, API, Platform, etc.).
2. Create workflows with the right PM approvers for each area.
3. Assign workflows at the parent page level with "apply to children."
4. From that point, any new or existing page under that subtree inherits the assignment.

Once workflows are assigned, your AI agent's preflight calls will confirm the right workflow resolves for each page before submitting.

A couple of things worth noting: ApprovalFlow for Confluence is Forge-native — it runs entirely inside Atlassian infrastructure with no external data transfer. And the preflight endpoint is particularly useful for CI/CD pipelines — your agent can validate everything before triggering the review cycle, so you never get a failed submission at runtime.

We're happy to walk through the setup for your specific page structure if that would help. Please book a free demo here

Related Info:

Blog: 

1) Introducing change sets and a new ApprovalFlow API 

Docs: 

1) Change Sets 

2) ApprovalFlow Rest API 

Happy to work closely with you on this one to ensure you get enough support for your workflows

Its free to try on Atlassian marketplace for 30 days: ApprovalFlow for Confluence

Best,

Team Flowdence

Note: We have only just launched so expect super fast support and product enhancements 

[Gareth Budge]

Hi @Levente Szabo _Midori_ @Adrian Hülsmann - B1NARY @Kristian Klima ,

Thanks for your replies and thoughts. I do appreciate you taking the time out of your day.

Yes I can see the considerations you all raise.

There are open source solutions that use Git and the Confluence API to version / publish content to Confluence, but the ones I've tried start with markdown which is very limited.

It would be great to see even a simple approval workflow to manage state from draft to published, but in any case you've guided me to the marketplace, so many thanks.

[Kristian Klima]

Hi @Gareth Budge 

a) you may wanna look at this question - about importing markdown to Confluence

https://community.atlassian.com/t5/Confluence-questions/Import-URL-with-markdown-and-display-via-Scroll-Viewport/qaq-p/2804569

b) Just last week, I tested a new solution that works Confluence's native Page Status features. It is a two-space solution using Ricksoft's Space Sync for Confluence and their free Pages Manager app.

The idea is that you have your workflow / page status going in one space, to which you import markdown files, then, upon the page reaching Done status (or any other that you set up), Space Sync moves it to another space.

Pages Manager allows you to change page status of multiple pages at once... thus becoming your push for a virtual branch.

[Adrian Hülsmann - B1NARY]

Hi @Gareth Budge

It is difficult to achieve something similar to git with Confluence. However, you could use Confluence automation for basic stuff, e.g., identifying pages that haven't been updated for some time.

However, as soon as you want more options for the content lifecycle, the go-to way is to use dedicated content lifecycle management plugins like Breeze.

Breeze automatically identifies outdated pages and implements review and archiving workflows to keep your pages up-to-date.

It's a feature-packed content lifecycle management solution and includes

• automated content analyses,
• page review and archiving workflows (approvals coming very soon),
• page and space ownership,
• reports and notifications,
• bulk archiving and deletion,
• analytics,
• data export for all your content, ownership, and status information
• and more to update outdated pages quickly and enhance collaboration.

👉 Anyone interested might Give it a try, or feel free to schedule an appointment with me for a personal demo.

Cheers and all the best, Adrian from B1NARY (we are the developers of Breeze)

[Kristian Klima]

Hi @Gareth Budge 

I think one of the main reasons to use Confluence is to avoid Git :)

Anyway, yes, the marketplace would be your source.

We're using Comala Document Approval (one of Appfire's workflow management apps) and Comala Publishing.

We have two Confluence spaces synced with Publishing. Source and Target.

In Source, we keep pages in Draft status with Doc Approval, once they're ready, move them to Complete. This triggers the Publishing app which transfers the page to the Target space. It's the same with new pages.

It's git-like with the difference that you can do that on the page level (page to page basis).

If you need to revert, revert the Source page to the previous version, and sync it manually to the Target space.

Works like a charm as the Publishing app swallows everything hook line and sinker (labels, third party macros, everything).

We then use the Target space to built our doc center from (with K15t's Scroll Viewport)

If you need semantic versioning, you'd do that in your Target space with Scroll Documents.

Having said all of the above, I've been rather vocal on calling for a proper actionable workflow in Confluence. Current solution is, essentially, a glorified label that doesn't really do anything.