SourceDocsGuides / Files from Git
Embed a file from GitHub, GitLab, Bitbucket or Azure DevOps in Confluence Cloud
Copying a README or an architecture document into Confluence works for a week; then the copy is out of date. SourceDocs shows the file itself: paste the link once, and the page follows the branch or tag you chose.
Steps
- Install SourceDocs for Confluence from the Atlassian Marketplace. A Confluence admin does this once for the site.
- Open the file in your Git provider's web interface and copy the address from the browser bar. For a README, the repository's main page link is enough.
- Edit a Confluence page, type
/gitand pick SourceDocs: File from Git. - Paste the link and click Preview to check the file, then Save and publish the page.
Which links work
| Provider | Example |
|---|---|
| GitHub | https://github.com/org/repo/blob/main/docs/architecture.mdhttps://github.com/org/repo shows the README |
| GitLab.com | https://gitlab.com/group/subgroup/repo/-/blob/main/docs/architecture.md |
| Bitbucket Cloud | https://bitbucket.org/workspace/repo/src/main/docs/architecture.md |
| Azure DevOps | https://dev.azure.com/org/project/_git/repo?path=/docs/architecture.md&version=GBmain |
| Your own server | GitLab self-managed or Dedicated, GitHub Enterprise Server and ghe.com, after an admin adds the server |
The branch, tag or commit in the link is what the page shows. Use main for "always current" and a tag such as v2.4.0 for documentation that should stay frozen at a release. Branch names with a slash, such as release/2.0, work too. The full list of link shapes is in the documentation.
What the file looks like
SourceDocs picks the rendering from the file type:
- Markdown (
.md,.markdown,.mdx) as on GitHub: tables, task lists, code blocks, alerts (> [!NOTE]), and Mermaid and PlantUML blocks drawn as diagrams. Relative links open the right file in the repository, images from the repository load (private ones too), and heading links jump within the page. - Diagrams:
.mmdand.mermaidfiles with Mermaid;.puml,.plantuml,.iumland.wsdfiles with PlantUML. - OpenAPI and Swagger YAML or JSON as an API reference with navigation, schemas and examples.
- Any other text file as source code with syntax highlighting for more than 40 languages, for example a configuration file, a SQL migration or an example client.
A bar above the content shows the provider, path, branch and the time of the last fetch, with a link to the file in the repository.
Private repositories
A Confluence administrator stores one read-only token per provider on the SourceDocs admin page (Confluence Settings → Apps → SourceDocs) and clicks Test. From then on, every macro on the site can show files from the repositories that token can read.
- Page authors and readers do not need a Git account or their own access.
- There is no OAuth app to approve in your Git organisation.
- The token is stored encrypted in Atlassian's Forge storage, is never shown again, and never reaches the browser.
Which token to create for each provider, with the smallest permissions that work, is described under private repositories.
Your own Git server
Companies that run GitLab or GitHub Enterprise themselves can add the server on the admin page. Atlassian then shows its own dialog, and an Atlassian administrator approves the connection to that server. The server must be reachable from Atlassian's cloud over HTTPS. See your own Git server.
How updates appear
SourceDocs fetches the file again at most every 10 minutes, so a merged change shows up on the page shortly after. Refresh on the page fetches the latest version immediately. Fetched files are kept inside your Atlassian site for those 10 minutes and then deleted.
Questions
Does Confluence search find the content?
The file is shown live from Git, not copied into the page, so Confluence's search indexes the page text around the macro but not the file. Add a sentence or two above the macro with the words people will search for.
What happens in PDF and Word export?
Markdown becomes real headings, paragraphs, tables and code blocks, so it paginates like the rest of the page. Diagrams are embedded as vector pictures, OpenAPI becomes printable tables, and each file starts with a "Source" line with the link and the fetch date.
How large can a file be?
Up to 16 MB per file and 1 MB per image. That is enough even for GitHub's own REST API description (13.5 MB). Large files travel compressed, and source files above 500 KB are shown without syntax highlighting so the page stays fast.
What does it cost?
Free for Confluence sites with up to 10 users. Above that, from 0.45 USD per user per month, with a 30-day free trial on the Marketplace.
More guides: Mermaid in Confluence · PlantUML in Confluence · Markdown in Confluence · OpenAPI in Confluence