Embed a GitHub file in Confluence
To embed a GitHub file in Confluence, add the Github file (Capable) macro to the page, connect your GitHub account, then pick the repository and file and select Add to page. Or paste the file's GitHub link straight into the editor. The file stays live: code is highlighted, Markdown is formatted and diagrams are drawn.
#Before you start
You need | Why |
|---|---|
Permission to edit the page | The macro is added in the Confluence editor. |
A GitHub account that can read the repository | The picker lists only repositories your connected accounts can see. A public file pasted as a link needs no connection. |
Readers of a private file need their own access | Each reader connects their own GitHub account. Nobody borrows yours. See Private file path. |
#Steps
Open the Confluence page and select Edit.
Type /Github and choose Github file (Capable).
On the macro, select Select File to open the Browse Git Repositories window.
If you have not connected GitHub yet, select Connect and authorise the app in the GitHub window that opens.
Type part of a repository name in Search repositories or paste URL..., or paste a GitHub file link and press Enter.
Open the repository, go into folders until you see the file, and select it to preview it.
Select Add to page, then publish the page.
Quicker: paste a github.com /blob/ link or a raw.githubusercontent.com link into the editor and it turns into the macro by itself, with the repository, branch and path taken from the link. See Auto-convert pasted GitHub links.
#What happens next
The file appears under a header showing owner/repo/path. The branch shows in brackets when it is not main. Readers can select Open on GitHub to jump to the file, and signed-in readers get Refresh content. The page byline counts the files, for example 1 file.
The macro reads the file from GitHub every time the page is viewed, so it always shows what is on the branch now. There is nothing to sync.
#If it does not work
The macro asks readers to Connect GitHub: the file is private and that reader has no connected account with access. See Readers see "Connect a GitHub account with access to this repository to view this file".
The picker says This file type cannot be rendered: the file type is not supported, for example a PDF or a zip file.
A pasted link stayed a link: see Pasted a GitHub URL and it did not turn into a macro.
#Related
One macro, the file as it is today.
