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
- Visit the Mermaid Diagram Sync Assistant on GitHub
- Click “Install” and choose your organization or personal account
- Select repositories (all or specific ones) where you want diagram sync functionality
- 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:
- Uninstall the GitHub App - Go to your GitHub Settings → Applications → Installed GitHub Apps and remove “Mermaid Diagram Sync Assistant”
- Clear any existing connections - This ensures no cached OAuth tokens remain
- Reinstall the GitHub App - Visit the Mermaid Diagram Sync Assistant page again
- Complete OAuth with new account - Log into your desired Mermaid Chart account during the OAuth flow
- 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:
- The bot commits the updated
.mmdfile(s) to the PR head branch. - It posts a PR comment per diagram with:
- A short summary
- Before / After Mermaid previews
- A Review Diagram link into Mermaid Chart
- 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
.mmdfiles from processing - Standard gitignore syntax - Supports
*wildcards,**recursive matching,?single character - Negation patterns - Use
!patternto 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) andexclude-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:
- Detects changes in your PR
- Finds
docs/authentication-flow.mmdreferences both modified files - Analyzes code changes and understands new 2FA flow
- Regenerates Mermaid diagram with new authentication steps and API calls
- Commits updated diagram: “Automated diagram update”
Result: Your architecture documentation accurately reflects your implementation before PR review.