Mermaid × GitHub Actions で自動ダイアグラム生成ワークフローを構築

2025年8月5日

Mermaid

Mermaid × GitHub Actions で自動ダイアグラム生成ワークフローを構築

現代のソフトウェア開発において、複雑なシステムやプロセスを視覚的に表現することは、チーム間の理解を深め、プロジェクトの成功に欠かせない要素となっています。しかし、手動での図表管理は時間がかかり、更新漏れや同期の問題が頻繁に発生します。

この記事では、MermaidとGitHub Actionsを組み合わせることで、コードの変更と連動して自動的に図表を生成・更新するワークフローの構築方法をご紹介します。一度設定すれば、あなたのプロジェクトのドキュメントは常に最新の状態を保ち、開発チーム全体の生産性が大幅に向上することをお約束いたします。

背景

ドキュメント作成における図表の重要性

現代の開発現場では、システムアーキテクチャやデータフロー、ワークフローなどを視覚的に表現することが、プロジェクトの成功に直結します。図表があることで、新しいメンバーの理解が早まり、ステークホルダーとのコミュニケーションも円滑になります。

特に以下のような場面で、図表の価値は計り知れません。

場面	図表の効果	具体例
1	新メンバーのオンボーディング	システム構成図による全体像の把握
2	ステークホルダーとの打ち合わせ	ビジネスフローの可視化
3	設計レビュー	データベース設計図による議論の促進
4	障害対応	エラーフローチャートによる迅速な原因特定
5	プロジェクト引き継ぎ	処理フローの詳細な文書化

手動での図表管理の課題

しかし、従来の手動による図表管理には多くの問題があります。私自身も開発現場で、以下のような経験を何度もしてきました。

更新忘れによる情報の陳腐化
コードは最新なのに、図表だけが古いバージョンのまま放置される問題です。これにより、新しいメンバーが間違った理解をしてしまうリスクが高まります。

複数人での編集による競合
PowerPointやDrawio等のツールを使用する場合、複数人が同時に編集すると、ファイルの競合が発生し、作業効率が大幅に低下します。

バージョン管理の困難さ
図表ファイルはバイナリファイルであることが多く、Gitでの差分確認や履歴管理が困難です。いつ、誰が、どのような変更を行ったかを追跡することが非常に困難になります。

CI/CDによる自動化の必要性

これらの課題を解決するために、CI/CD（継続的インテグレーション・継続的デリバリー）の概念を図表管理にも適用することが重要です。

コードの変更に連動して図表も自動的に更新されることで、常に一貫性のある状態を保つことができます。これにより、開発チームは本来の価値創造活動に集中でき、ドキュメントメンテナンスの負担から解放されるのです。

課題

Mermaidファイルの手動更新による非効率性

多くの開発チームが直面している最大の課題は、Mermaidファイルの手動更新作業です。コードを修正するたびに、関連する図表も手動で更新する必要があり、これが開発者の大きな負担となっています。

具体的には、以下のような問題が発生します。

時間的コストの増大
小さな機能追加でも、関連する複数の図表を更新する必要があり、実装時間の30%以上が図表更新に費やされることも珍しくありません。

人的ミスの発生
急いで更新作業を行うと、図表の記述ミスや更新漏れが発生し、後々の混乱を招くことになります。

図表とドキュメントの同期問題

プロジェクトが進行するにつれて、コードの実装と図表の内容に乖離が生じることは避けられません。この同期問題は、以下のような深刻な影響をもたらします。

問題	影響	発生頻度
1	古い図表による誤解	毎週発生
2	設計レビューでの混乱	月に2-3回
3	新メンバーの誤った理解	新人参加時
4	ステークホルダーへの誤情報提供	四半期に1-2回

私が以前担当したプロジェクトでは、データベース設計図の更新を忘れたために、新しいメンバーが存在しないテーブルを参照するコードを実装してしまい、3日間の作業が無駄になったという苦い経験もあります。

チーム開発での図表管理の複雑化

チーム規模が大きくなるほど、図表管理の複雑さは指数関数的に増加します。複数の開発者が同じ図表を参照し、それぞれが異なるタイミングで更新を行う場合、以下のような問題が発生します。

責任の所在の不明確化
誰がどの図表の更新責任を持つのかが曖昧になり、結果として誰も更新しない状況が生まれます。

更新タイミングの調整困難
複数の機能が並行して開発される場合、図表の更新タイミングを調整することが困難になり、常に不整合状態が続くことになります。

解決策

GitHub ActionsによるMermaid図表の自動生成

これらの課題を根本的に解決するために、GitHub ActionsとMermaidを組み合わせた自動生成システムを構築します。この仕組みにより、コードの変更と同時に図表も自動的に更新され、常に最新の状態を保つことができます。

自動化のメリット

一貫性の保証: コードと図表が常に同期された状態を維持
作業効率の向上: 手動更新作業からの解放
品質の向上: 人的ミスの排除
透明性の確保: 変更履歴の完全な追跡

プルリクエスト連動による自動更新システム

プルリクエストのワークフローに図表生成プロセスを組み込むことで、コードレビューと同時に図表の確認も行えるようになります。

これにより、レビュアーは実装内容と図表の整合性を同時にチェックでき、より質の高いレビューが可能になります。また、マージ後は自動的に本番環境の図表も更新されるため、常に最新の状態が保たれます。

成果物の自動配置機能

生成された図表は、GitHub Pagesやその他のホスティングサービスに自動的に配置されます。これにより、チームメンバーやステークホルダーは、いつでも最新の図表にアクセスできるようになります。

具体例

基本的なMermaidファイルの作成

まず、プロジェクトのルートディレクトリにdocsフォルダを作成し、Mermaidファイルを配置します。以下は、簡単なフローチャートの例です。

markdown```mermaid
graph TD
    A[開始] --> B{条件判定}
    B -->|Yes| C[処理A実行]
    B -->|No| D[処理B実行]
    C --> E[終了]
    D --> E
```

この例では、基本的な条件分岐を含むフローチャートを定義しています。Mermaidの記法はシンプルで直感的なため、プログラミング経験があれば簡単に習得できます。

次に、より複雑なシステム構成図を作成してみましょう。

markdown```mermaid
graph LR
    subgraph "Frontend"
        A[React App]
        B[Redux Store]
    end
    
    subgraph "Backend"
        C[Express Server]
        D[GraphQL API]
    end
    
    subgraph "Database"
        E[PostgreSQL]
        F[Redis Cache]
    end
    
    A --> C
    B --> A
    C --> D
    D --> E
    C --> F
```

このように、サブグラフを使用することで、複雑なシステムの構成を階層的に表現できます。各コンポーネント間の関係も明確に示されており、新しいメンバーでも全体像を素早く理解できます。

GitHub Actionsワークフロー設定

次に、GitHub Actionsのワークフローファイルを作成します。.github/workflows/generate-diagrams.ymlというファイルを作成し、以下の内容を記述します。

yamlname: Generate Mermaid Diagrams

on:
  push:
    branches: [ main, develop ]
    paths:
      - 'docs/**/*.md'
  pull_request:
    branches: [ main ]
    paths:
      - 'docs/**/*.md'

jobs:
  generate-diagrams:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout repository
      uses: actions/checkout@v4
      with:
        fetch-depth: 0

このワークフローでは、mainまたはdevelopブランチへのプッシュ、およびプルリクエストをトリガーとして実行されます。pathsフィルターにより、docsフォルダ内のMarkdownファイルが変更された場合のみに限定しています。

続いて、Mermaid CLIのセットアップとファイル検索の処理を追加します。

yaml    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '18'
        
    - name: Install Mermaid CLI
      run: |
        yarn global add @mermaid-js/mermaid-cli
        echo "$(yarn global bin)" >> $GITHUB_PATH
        
    - name: Find Mermaid files
      id: find-files
      run: |
        FILES=$(find docs -name "*.md" -exec grep -l "```mermaid" {} \;)
        echo "files<<EOF" >> $GITHUB_OUTPUT
        echo "$FILES" >> $GITHUB_OUTPUT
        echo "EOF" >> $GITHUB_OUTPUT

ここでは、Node.jsのセットアップを行い、Mermaid CLIをグローバルにインストールしています。その後、docsフォルダ内でMermaidコードブロックを含むMarkdownファイルを検索しています。

次に、実際の図表生成処理を実装します。

yaml    - name: Generate diagrams
      if: steps.find-files.outputs.files != ''
      run: |
        mkdir -p output/diagrams
        
        while IFS= read -r file; do
          if [ -n "$file" ]; then
            echo "Processing: $file"
            filename=$(basename "$file" .md)
            
            # Extract mermaid code blocks and generate images
            awk '/```mermaid/,/```/ {
              if ($0 !~ /```/) print $0
            }' "$file" > "temp_${filename}.mmd"
            
            if [ -s "temp_${filename}.mmd" ]; then
              mmdc -i "temp_${filename}.mmd" \
                   -o "output/diagrams/${filename}.png" \
                   -t dark \
                   --width 1200 \
                   --height 800
              echo "Generated: output/diagrams/${filename}.png"
            fi
            
            rm -f "temp_${filename}.mmd"
          fi
        done <<< "${{ steps.find-files.outputs.files }}"

この処理では、見つかったMarkdownファイルから Mermaidコードブロックを抽出し、PNG画像として出力しています。--widthと--heightオプションで画像サイズを指定し、-t darkでダークテーマを適用しています。

エラーハンドリングと結果の確認処理も追加しましょう。

yaml    - name: Verify generated files
      run: |
        if [ -d "output/diagrams" ]; then
          echo "Generated diagrams:"
          ls -la output/diagrams/
          
          # Check if any files were actually generated
          file_count=$(find output/diagrams -name "*.png" | wc -l)
          if [ "$file_count" -eq 0 ]; then
            echo "Error: No diagram files were generated"
            exit 1
          fi
          
          echo "Successfully generated $file_count diagram(s)"
        else
          echo "Warning: No diagrams directory found"
        fi
        
    - name: Upload diagrams as artifacts
      if: success()
      uses: actions/upload-artifact@v4
      with:
        name: generated-diagrams
        path: output/diagrams/
        retention-days: 30

最後に、生成した図表をGitHub Pagesにデプロイする処理を追加します。

yaml    - name: Deploy to GitHub Pages
      if: github.ref == 'refs/heads/main' && success()
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./output
        destination_dir: diagrams
        
    - name: Comment PR with diagram links
      if: github.event_name == 'pull_request' && success()
      uses: actions/github-script@v7
      with:
        script: |
          const fs = require('fs');
          const path = require('path');
          
          if (fs.existsSync('output/diagrams')) {
            const files = fs.readdirSync('output/diagrams');
            const diagrams = files.filter(f => f.endsWith('.png'));
            
            if (diagrams.length > 0) {
              let comment = '## 📊 Generated Diagrams\n\n';
              comment += 'The following diagrams have been generated:\n\n';
              
              diagrams.forEach(diagram => {
                const name = path.basename(diagram, '.png');
                comment += `- **${name}**: [View Diagram](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})\n`;
              });
              
              github.rest.issues.createComment({
                issue_number: context.issue.number,
                owner: context.repo.owner,
                repo: context.repo.repo,
                body: comment
              });
            }
          }

自動生成された図表の確認

ワークフローが正常に実行されると、以下の方法で結果を確認できます。

Actionsタブでの実行結果確認

GitHub リポジトリのActionsタブから、ワークフローの実行状況を確認できます。成功した場合、以下のようなログが出力されます。

bash✅ Processing: docs/system-architecture.md
✅ Generated: output/diagrams/system-architecture.png
✅ Processing: docs/data-flow.md  
✅ Generated: output/diagrams/data-flow.png
✅ Successfully generated 2 diagram(s)

エラーが発生した場合は、以下のようなメッセージが表示されます。

vbnet❌ Error: Command failed with exit code 1
❌ mmdc: Error: Cannot find module 'puppeteer-core'
❌ Error: No diagram files were generated

このようなエラーが発生した場合は、依存関係の問題が考えられます。以下のように修正できます。

yaml    - name: Install dependencies with puppeteer
      run: |
        yarn global add @mermaid-js/mermaid-cli puppeteer
        export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=false

プルリクエストでの自動コメント

プルリクエストを作成すると、ボットが自動的にコメントを追加し、生成された図表への直接リンクを提供します。

これにより、レビュアーは実装内容と図表の整合性を同時に確認でき、より効率的なレビューが可能になります。

GitHub Pagesでの公開確認

メインブランチにマージされた図表は、GitHub Pagesに自動的に公開されます。以下のURLでアクセスできます。

inihttps://[username].github.io/[repository]/diagrams/[diagram-name].png

これにより、チームメンバーやステークホルダーは、いつでも最新の図表にアクセスできるようになります。

トラブルシューティング

実際の運用では、以下のようなエラーに遭遇することがあります。

Puppeteerのインストールエラー

swiftError: Failed to launch the browser process!
ENOENT: no such file or directory, open '/opt/hostedtoolcache/node/18.19.0/x64/lib/node_modules/@mermaid-js/mermaid-cli/node_modules/puppeteer/.local-chromium/linux-1095492/chrome-linux/chrome'

この場合、以下の対処法を試してください。

yaml    - name: Install Chromium dependencies
      run: |
        sudo apt-get update
        sudo apt-get install -y chromium-browser
        export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

メモリ不足エラー

大きな図表を生成する際に、以下のエラーが発生することがあります。

vbnetError: Page crashed!
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

この場合、Node.jsのメモリ制限を増加させます。

yaml    - name: Generate diagrams with increased memory
      run: |
        export NODE_OPTIONS="--max-old-space-size=4096"
        mmdc -i input.mmd -o output.png