confluence-publisher

A one-way publishing pipeline that syncs GitHub Markdown files to Confluence pages.

GitHub is the source of truth. Confluence is the generated presentation layer.

Quick start

1. Add a confluence-manifest.yaml to your repository root.
2. Copy an example workflow from examples/workflows/ into .github/workflows/.
3. Add the three required secrets/variables to your repository settings.
4. Push or trigger manually — pages appear in Confluence within minutes.

See docs/ONBOARDING.md for a full step-by-step guide.

# confluence-manifest.yaml
defaults:
  space_id: ENG
  parent_id: '123456'

pages:
  docs/architecture.md:
    title: Architecture Overview
    page_id: '234567'         # existing Confluence page ID
  docs/runbook.md:
    title: Operations Runbook # no page_id — auto-created on first publish

# .github/workflows/publish-to-confluence.yml (minimal)
- uses: pipewell/confluence-publisher@v1
  with:
    confluence-base-url: ${{ vars.CONFLUENCE_BASE_URL }}
    confluence-api-token: ${{ secrets.CONFLUENCE_API_TOKEN }}
    confluence-email: ${{ vars.CONFLUENCE_EMAIL }}

Using a fine-grained/scoped Atlassian API token? See docs/ONBOARDING.md — these are rejected on the direct tenant domain and need confluence-cloud-id set instead.

What it does

• Triggers on push to main when files under docs/**/*.md change
• Converts Markdown to Confluence Storage Format using a custom mistletoe renderer
• Manages page identity via a checked-in YAML manifest (page IDs, not titles)
• Auto-creates pages when page_id is absent; writes the new ID back via a [skip ci] commit
• Uploads local images and Mermaid diagrams as page attachments
• Detects edit conflicts (Confluence version ahead of last published) and warns or fails
• Stores the Git commit SHA in the Confluence version message for traceability
• Adds an auto-generated banner to each page (source file, commit SHA, tool attribution) -- configurable via defaults.attribution in the manifest or --no-attribution
• Treats missing images, Mermaid render failures, and upload errors as hard build failures

Failure semantics

All failures exit non-zero. There are no silent failures.

The "Commit manifest state" step uses if: always() so page_id values are committed to the repo even when the publish step exits non-zero, preserving the retry guarantee across CI runs.

Supported Markdown

Scope

This tool is intentionally narrow:

• One-way only. It does not sync Confluence edits back to GitHub.
• Not a real-time mirror. It runs on push and on a nightly validation schedule.
• Not a general-purpose renderer. It targets the Confluence Storage Format features needed for engineering documentation.

Known limitations

• Inline comments lose their anchor on republish. Confluence anchors an inline comment by embedding markup directly in the page body around the highlighted text. Every publish replaces the full page body with freshly-converted Markdown, so that anchor markup doesn't survive -- the comment thread is typically detached rather than deleted, but it no longer points at any specific text. Footer/page-level comments are unaffected, since they're stored separately from the body and never touched by this tool. Tracked in #11.

Documents