Skip to main content

GitHub Markdown Sync for Confluence

Keep docs in GitHub. Read them in Confluence.

Overview​

Developers write documentation in Markdown, stored in GitHub alongside their code. But PMs, stakeholders, and non-technical teams live in Confluence. GitHub Markdown Sync bridges this gap with automatic one-way sync: push to GitHub, pages update in Confluence.

How It Works​

  1. Connect — Add your GitHub repo via a personal access token
  2. Map — Choose which folder to sync and which Confluence space to sync into
  3. Sync — Pages are created and updated automatically

Features​

  • Automatic sync on push — GitHub webhook triggers updates within seconds
  • Scheduled sync fallback — Hourly background sync catches anything webhooks miss
  • Smart change detection — Only pages with actual changes are updated
  • Frontmatter support — YAML frontmatter controls page titles and labels
  • Folder-to-space mapping — Map a GitHub directory to a Confluence space
  • Works with private repos — GitHub PAT stored securely in Forge Storage
  • Runs on Forge — 100% serverless on Atlassian's infrastructure

Configuration​

Setting Up a Connection​

  1. Install the app from the Atlassian Marketplace
  2. Go to the app settings in your Confluence space
  3. Add a GitHub connection:
    • Personal Access Token — a GitHub PAT with repo read access
    • Repository — owner/repo format
    • Branch — the branch to sync from (e.g., main)
    • Source path — the folder in the repo containing Markdown files
    • Target space — the Confluence space to publish to

Frontmatter​

Control page metadata with YAML frontmatter at the top of your Markdown files:

---
title: My Page Title
labels:
  - documentation
  - api
---

# Page content starts here...

Webhook Setup (Optional)​

For instant sync on push, add a webhook to your GitHub repo:

  1. Go to your repo Settings > Webhooks
  2. Add the webhook URL provided in the app settings
  3. Select "push" events

Markdown Conversion​

MarkdownConfluence
Headings (# ## ###)Heading styles
Code blocksCode macro with syntax highlighting
TablesConfluence tables
ImagesInline images (resolved from repo)
LinksConfluence links
Bold, italic, listsNative formatting

Frequently Asked Questions​

Is this one-way or two-way sync?​

One-way only: GitHub → Confluence. Changes made in Confluence are overwritten on the next sync. If you need to edit content, edit the Markdown file in GitHub and let the sync push the update.

Does it support GitHub Enterprise?​

The app connects to GitHub via personal access tokens and the GitHub REST API. It works with github.com (public and private repos). GitHub Enterprise Server support depends on whether the Forge runtime can reach your Enterprise instance's API — contact us if you need this.

What happens to pages if I disconnect a repo?​

Existing Confluence pages remain in place — they're not deleted when you remove a connection. They simply stop receiving updates. You can continue editing them manually in Confluence.

Can I sync multiple folders to different spaces?​

Yes. You can create multiple connections, each mapping a different GitHub folder to a different Confluence space. This is useful when you have separate documentation for different teams or products.

How does it handle images in Markdown?​

Images referenced in Markdown files are resolved from the GitHub repo and embedded in the Confluence page. Relative image paths (e.g., ./images/diagram.png) are resolved relative to the Markdown file's location in the repo.

Does it preserve Confluence page hierarchy?​

The app creates pages in a flat structure within the target space. If your GitHub folder has subdirectories, each Markdown file still becomes a top-level page. Page ordering follows the order defined in the sidebar configuration or alphabetical order by filename.

Troubleshooting​

ProblemCauseSolution
Pages not updating after pushWebhook may not be configured or is failingCheck GitHub repo Settings > Webhooks for delivery errors. Fall back to hourly scheduled sync.
Page content looks wrongUnsupported Markdown syntaxThe app supports CommonMark. GitHub-flavored extensions (e.g., task lists, alerts) may not render correctly.
"Token expired" errorGitHub PAT has expiredGenerate a new personal access token in GitHub and update it in the app settings
Images not showingImage path is incorrect or repo is privateEnsure image paths are relative to the Markdown file. For private repos, the PAT must have repo scope (not just public_repo).
Sync creates duplicate pagesFile was renamed in GitHubThe app tracks files by path. Renaming a file creates a new page. Delete the old Confluence page manually.

Data Security & Privacy​

Data storageNo data stored outside Atlassian
Data processingNo data processed outside Atlassian (except GitHub API for fetching Markdown)
Data residencyExclusively within Atlassian apps and services
GDPRData processor — Confluence page content, GitHub repository content (Markdown files)
Security contactsupport@alpinate.com