Mermaid Diagram Sync Assistant

Keep Mermaid diagrams automatically in sync with source code changes in pull requests.

The Mermaid Diagram Sync Assistant is an intelligent GitHub app that monitors your pull requests and updates Mermaid diagrams when related source files are modified. When a PR is opened, synchronized, or reopened, the app scans the changed files, finds diagrams connected to those files, regenerates the affected diagrams, and adds the updates back to the PR with clear bot attribution — so your docs stay current during review.

Getting Started: Connect Your Mermaid Chart Account

GitHub App Installation & OAuth Setup

To use the Mermaid Diagram Sync Assistant, you need to connect your Mermaid Chart account to the GitHub App:

Step 1: Install the GitHub App

  1. Visit the Mermaid Diagram Sync Assistant on GitHub
  2. Click “Install” and choose your organization or personal account
  3. Select repositories (all or specific ones) where you want diagram sync functionality
  4. GitHub will redirect you to complete the OAuth connection

Step 2: Connect Your Mermaid Chart Account After installation, you’ll be redirected to our OAuth flow:

  • If you’re logged into Mermaid Chart: Your GitHub installation will be linked immediately, and you’ll be redirected to your GitHub dashboard
  • If you’re not logged in: You’ll be redirected to log into Mermaid Chart first, then your accounts will be automatically linked

Step 3: Verify Connection Once connected, visit your Mermaid Chart GitHub dashboard at /app/github to:

  • See your linked GitHub installations
  • Manage repository access
  • Monitor your AI credit usage for diagram updates

Account Management & Switching

Changing Your Connected Mermaid Chart Account

If you need to logout or switch to a different Mermaid Chart account, you must complete a full reinstallation process:

Required Steps:

  1. Uninstall the GitHub App - Go to your GitHub Settings → Applications → Installed GitHub Apps and remove “Mermaid Diagram Sync Assistant”
  2. Clear any existing connections - This ensures no cached OAuth tokens remain
  3. Reinstall the GitHub App - Visit the Mermaid Diagram Sync Assistant page again
  4. Complete OAuth with new account - Log into your desired Mermaid Chart account during the OAuth flow
  5. Verify new connection - Check your new account’s GitHub dashboard to confirm the installation is linked correctly

Important Notes:

  • There’s currently no “logout” or “switch account” feature within the app
  • Each GitHub installation can only be linked to one Mermaid Chart account at a time
  • Uninstalling and reinstalling will not affect your existing diagrams or repositories
  • Your AI credit usage history remains with each respective Mermaid Chart account

Diagram review workflow

When diagrams are regenerated for a PR:

  1. The bot commits the updated .mmd file(s) to the PR head branch.
  2. It posts a PR comment per diagram with:
    • A short summary
    • Before / After Mermaid previews
    • A Review Diagram link into Mermaid Chart
  3. The reviewer signs in (GitHub OAuth when needed), opens the diagram in the editor, Accepts or Rejects the change, then can Push to GitHub. Access is limited to the GitHub App installation owner and any users on the installation’s reviewers allowlist.

Reviewers (Mermaid Chart settings)

Repository / installation admins can manage reviewers in the Mermaid Chart web app: Settings → GitHub Integration → Reviewers

  • Add Mermaid Chart users by email to allow them to open review links and push accepted diagram updates.
  • Remove reviewers when access should be revoked.
  • Applies to reviews for repos under that GitHub App installation (public and private).

.mermaidignore Configuration

Control which files and diagrams are considered using .mermaidignore files (similar to .gitignore):

Key Features:

  • Source file filtering - Exclude source files from triggering diagram updates
  • Diagram file filtering - Completely exclude specific .mmd files from processing
  • Standard gitignore syntax - Supports * wildcards, ** recursive matching, ? single character
  • Negation patterns - Use !pattern to create exceptions and include previously excluded files
  • Pattern precedence - Later patterns override earlier ones for complex filtering rules

Example .mermaidignore :

# Ignore temporary and build files
*.log
*.tmp
build/
node_modules/

# Ignore test files but keep integration tests
**/*test*
!src/tests/integration.test.js

# Ignore draft diagrams except important ones
draft/**/*.mmd
!temp-important.mmd

Mermaid Diagram Sync Assistant Configuration

Control which PR branches the bot processes using .smart-mermaid-updates.yml:

Key Features:

  • Branch filtering - Exclude PR head branches using exact names or wildcard patterns
  • Flexible patterns - Supports exact matches (main), wildcards (feature/*), negation (!pattern)
  • Multiple syntax - Both excludeBranches (camelCase) and exclude-branches (kebab-case)
  • Smart processing - If branch matches exclusion pattern, entire PR is skipped

Example configurations:

# Basic exclusions
excludeBranches:
  - experimental
  - draft/*
  - temp/*
  - wip/*

# Advanced: exclude all except specific branches
excludeBranches:
  - '*'              # Exclude all branches
  - '!feature/*'     # Except feature/* branches  
  - '!main'          # And except main branch

Real-World Example

Scenario: You modify src/auth/UserService.js to add two-factor authentication and update src/api/AuthController.js for new endpoints.

Bot Process:

  1. Detects changes in your PR
  2. Finds docs/authentication-flow.mmd references both modified files
  3. Analyzes code changes and understands new 2FA flow
  4. Regenerates Mermaid diagram with new authentication steps and API calls
  5. Commits updated diagram: “Automated diagram update”

Result: Your architecture documentation accurately reflects your implementation before PR review.