Your engineers write the README, setup guide and architecture notes in GitHub, next to the code. Everyone else reads Confluence. So the same content lives in two places, and the Confluence copy is out of date the week after someone pastes it in.
This is one of the most-viewed questions on Community, so here are the options and their trade-offs.
Option 1: Copy and paste
Fast, works everywhere, and stale the moment the file changes. Fine for a one-off, risky for anything people rely on, like onboarding steps or API docs.
Option 2: Paste the link as a Smart Link
Confluence turns a GitHub URL into a Smart Link with a title and a preview card. That's great for pointing people to a file, but it doesn't show the file's contents on the page. Readers still have to click through to GitHub, and many of them don't have a GitHub account.
Option 3: Publish from CI
Some teams write a pipeline step that converts Markdown and pushes it to Confluence through the REST API. It keeps pages in sync, but you own the script: page IDs, formatting edge cases, images, permissions and API tokens all need maintenance.
Option 4: Render the file live with an app
Apps like GitHub Links for Confluence (made by our team) let you paste a GitHub URL and render the content on the page:
- Copy the URL of the file in GitHub, for example
https://github.com/acme/payments/blob/main/README.md. - Paste it into a Confluence page. It turns into a card for the file; expand it and the rendered README appears right on the page.
- Need only part of a file? Add a line range (
#L5-L12) to embed just that snippet, which is handy for config examples in a runbook.
The same works for issues, pull requests, releases, commits and gists, so a release page can show the actual PRs that shipped instead of a hand-maintained list.
Private repositories: an admin connects the GitHub App once and chooses which repositories it can read. Readers don't need their own GitHub account.
GitHub Enterprise: GitHub Enterprise Cloud is supported, including data residency (*.ghe.com). GitHub Enterprise Server is not supported today.
Which should you pick?
- One-off page, rarely changes: copy and paste.
- Just pointing people to the source: Smart Link.
- Large docs set with a dedicated platform team: CI publishing.
- Living docs that non-developers read: render the file live, so GitHub stays the single source of truth.
How are you handling this today? If you've built a CI pipeline for it, I'd love to hear what tripped you up.
Further reading: Supported GitHub link types, Embedding file segments