Publish GitHub Markdown to Confluence While Checking for Manual-Edit Conflicts

1. Read-Only Destination Preflight & Version-Drift Detection

Blind CI/CD documentation scripts push Markdown commits directly to the Confluence REST API by incrementing the remote version number without verifying who authored the latest revision. DocBrancher records the expectedConfluenceVersion and content SHA-256 from the last synchronization. When you run a destination preflight, DocBrancher queries the remote space in read-only mode and flags any page whose actualRemoteConfluenceVersion exceeds expectedConfluenceVersion.

// Illustrative conflict example
{
  "repoPath": "docs/architecture/overview.md",
  "confluencePageTitle": "System Architecture Overview",
  "preflightAction": "CONFLICT_DETECTED",
  "expectedConfluenceVersion": 3,
  "actualRemoteConfluenceVersion": 4,
  "conflictReason": "Remote Confluence page advanced from v3 to v4 outside Git synchronization."
}

2. Side-by-Side Storage XHTML Inspection & Explicit Resolution

When a version conflict is detected during preflight, DocBrancher refuses to publish that page until an explicit operator decision is selected. You can inspect the compiled GitHub Storage XHTML alongside the remote Confluence Storage XHTML and choose either PRESERVE_HUMAN_EDIT (skip overwriting the remote page so the manual Confluence v4 edit remains intact) or FORCE_OVERWRITE_FROM_GITHUB (publish the GitHub Markdown compilation as Confluence v5).

Resolution Option A: PRESERVE_HUMAN_EDIT
  -> Skips remote write; retains Confluence Cloud v4 as-is.

Resolution Option B: FORCE_OVERWRITE_FROM_GITHUB
  -> Publishes compiled GitHub Storage XHTML as Confluence Cloud v5.

3. Operational Boundaries, Race-Condition Limits & Explicit Non-Goals

Engineering teams evaluating DocBrancher should review three operational boundaries: (1) Version checks detect manual Confluence edits present at preflight and sync execution time rather than holding an exclusive distributed lock against mid-request concurrent edit races; (2) Scoped workbench runs and Assisted Publishing Pilots cover up to 20 Markdown files (.md, .markdown, .mdx) per run across repository root and docs/; (3) DocBrancher compiles standard GitHub-Flavored Markdown and relative links to Confluence Storage XHTML and does not execute custom MkDocs Python plugins, Jinja2 macros, or static-site theme hooks.

Frequently Asked Questions