How to Embed Git Files in Confluence Live, Always in Sync

TL;DR

Git for Confluence embeds GitLab files directly into Confluence pages — Markdown, Mermaid diagrams, OpenAPI specs, source code, and 30+ other formats. Content stays in GitLab. Confluence pulls it live on every page view. No storage, no sync jobs, no duplicated docs. Free for teams up to 10 users.

Note: This guide uses GitLab as the reference example, but Git for Confluence supports GitHub, Bitbucket, and Azure DevOps the same way. Just paste the URL from your provider — setup details vary slightly per provider, but the workflow is identical.

Why GitLab and Confluence don't connect out of the box

Developers live in GitLab. READMEs, architecture diagrams, API specs, runbooks, security policies — all of it lives in repositories, version-controlled and accurate.

Business and non-technical teams live in Confluence. Product managers, marketers, architects, technical writers, and support teams use Confluence to stay aligned. They don't have GitLab access, and they shouldn't need it just to read a diagram.

The standard workaround is copy-paste: someone copies content from GitLab into a Confluence page. Within days, the source changes. The Confluence version doesn't. Now there are two versions of the truth — and the wrong one is the one most people are reading.

Stale docs aren't just inconvenient. Teams make decisions based on them. Someone follows an outdated runbook and breaks something. An auditor asks for compliance docs and gets a version from six months ago. The Confluence page becomes a liability instead of an asset.

How Git for Confluence works

Git for Confluence closes the gap between GitLab and Confluence. GitLab content stays in GitLab. Confluence pages pull it live. One source of truth, accessible everywhere work happens.

There's no scheduled sync, no webhook to configure, no pipeline to maintain. File content is never stored on Git for Confluence's servers. Every page view triggers a fresh fetch from your repository.

For private repositories, content is fetched via an authenticated user (OAuth) or an admin-configured access token. Viewers — including people without a GitLab account — can see embedded content as long as the token has access.

What you can embed: 30+ file formats

Git for Confluence renders files visually — not as raw text. Supported categories:

Diagrams from GitLab in Confluence

Most teams store architecture diagrams as images in Lucidchart or draw.io. Those diagrams drift — nobody updates them when the system changes because it's a separate task, disconnected from the development workflow.

Diagrams-as-code changes this. A Mermaid or PlantUML file lives in the same repository as the code it describes — part of the same pull request, reviewed, versioned, and traceable to a commit.

Git for Confluence renders these files visually in Confluence. A .mermaid file becomes a flowchart. A .puml file becomes a sequence diagram. A Structurizr file renders as a C4 architecture diagram.

When docs live with code, they stay accurate. No Lucidchart license needed. No diagram going stale because someone forgot to update it.

Try it: embed a GitLab file in under 5 minutes

Public repository

Private repository

GitLab self-managed

GitLab self-managed instances (version 14.4+) are fully supported. Admins add the self-managed provider once under Manage apps → Git for Confluence Administration → Add a Self Managed Provider. After that, URLs from that instance are recognized automatically.

Access control: individual vs. managed

Individual access (OAuth 2.0)

Users connect their own GitLab accounts via OAuth. They can embed and share any content their account has access to. Best for smaller teams where everyone has GitLab accounts and direct control matters.

Managed access (token-based)

An admin configures one access token at the organization level. All content shared via managed access is served through that token. Viewers — including people without a GitLab account — can see embedded content as long as the token has access.

Admins control which Confluence user groups can embed content. There's a full activity log. Revoking the token instantly stops all sharing. Best for larger organizations with centralized governance requirements or non-technical stakeholders who need read access without GitLab accounts.

Both modes can coexist. Individual users can use OAuth; the organization can use managed access for shared documentation spaces.

How to get started

‍

Looking for security certifications, enterprise compliance details, and how Git for Confluence compares to alternatives? Read our Security, Compliance & Forge Guide.

Try Git for Confluence free for 30 days. Free for teams up to 10 users. Up and running in under 5 minutes. Start free trial on Marketplace

Frequently asked questions