Skip to content
Yamuno
Browse

GitHub, GitLab and Bitbucket

Diagrams that live in a repository, as a .mmd file or a ```mermaid block in a Markdown file, can be imported into a page and stay linked to their file. Editors can then load the latest version, or write their changes back as a commit.

It works with private repositories. A Confluence admin connects each service once for the whole site, in Mermaid Diagram settings → Repositories.

Importing a diagram

  1. In the editor, click Insert → From GitHub, From GitLab or From Bitbucket.
  2. Pick a repository, a branch and a file. The file list shows .mmd, .mermaid and Markdown files, diagram files first. You can also paste a link to the file instead.
  3. For a Markdown file, choose the diagram in the file. Each ```mermaid block is listed by the heading above it.
  4. Check the preview and click Import.

The diagram replaces the code in the editor. An untitled diagram is named after the heading or the file.

Keeping it in sync

A linked diagram shows its file name in the editor's top bar. Its menu has:

  • Refresh from GitHub / GitLab / Bitbucket: loads the latest version of the file into the editor.
  • Commit to GitHub / GitLab / Bitbucket: writes the code in the editor back to the same file and branch. In a Markdown file only that diagram's block is replaced; the rest of the file is kept.
  • Open on GitHub / GitLab / Bitbucket: the file's page.
  • Unlink: keeps the diagram and forgets the file.

Save the diagram afterwards, so the page shows the new version too.

If someone changed the file since it was loaded, a commit is refused and nothing is overwritten: refresh first, then make the change again. Changes to other files in the repository don't count.

Commits name the Confluence editor in the message ("Committed from Confluence by …"). Admins can turn commits off per service with Allow commits.

Who can see what

  • Readers see the diagram saved on the page. They don't need access to the repository, and nothing is loaded from it when the page opens.
  • Editors can import from every repository the site's connection can reach, and refresh or commit any linked diagram. They don't connect their own accounts.
  • The page doesn't change when the file changes on its own: an editor refreshes and saves it.

If a connection is removed, or its token expires, diagrams keep showing. Only Refresh and Commit stop working until an admin connects again.

Connecting GitHub

GitHub uses a private GitHub App that your organization owns. Yamuno doesn't run a GitHub App or hold your keys.

  1. In Mermaid Diagram settings → Repositories → GitHub, enter your GitHub organization (or leave it blank for a personal account) and click Connect GitHub.
  2. Approve api.github.com in Atlassian's dialog.
  3. GitHub opens in a new tab and creates the app in your organization. Choose which repositories it can reach and click Install.

The settings card then shows the app, where it is installed, and Change repository access. Disconnect removes it from Confluence; the app stays on GitHub, and the card links to where you can delete it.

Connecting GitLab

GitLab uses an access token you create. It works with gitlab.com and self-managed GitLab.

Token Editors can reach Notes
Group access token (recommended) Every project in the group and its subgroups GitLab Premium or Ultimate on gitlab.com, any self-managed GitLab
Project access token One project Same as group tokens
Personal access token Every project that person can access Works on every plan. Commits appear under that person, and the connection stops if they leave

Give the token the api scope (or read_api to import without committing) and at least the Developer role (Maintainer to commit to protected branches). Then, in Repositories → GitLab, enter your GitLab address, paste the token, click Connect GitLab and approve the address in Atlassian's dialog.

Connecting Bitbucket

Bitbucket Cloud uses an access token you create.

Token Editors can reach Notes
Workspace access token (recommended) Every repository in the workspace Bitbucket Premium
Repository access token One repository Every plan

Give it the Repositories: Read and Write permissions (Read only, to import without committing). Then, in Repositories → Bitbucket, enter your workspace ID (from bitbucket.org/<workspace>), paste the token, click Connect Bitbucket and approve api.bitbucket.org in Atlassian's dialog.

Good to know

  • Tokens are stored encrypted in the app's Forge storage and are never shown again. Disconnect removes them from Confluence; revoke them in GitLab or Bitbucket too if you no longer need them.
  • Each service has one connection per Confluence site.
  • Files up to 1 MB, and up to 1,000 diagram and Markdown files per branch, are listed.
  • For public files on other sites, use Import from a URL.

Stuck on something this page does not cover? Ask the developers.