【Doxygen実践#3】GitHub Actions + GitHub PagesでCI自動ドキュメント生成を実現する

Last updated at 2026-07-07Posted at 2026-07-07

本記事はシリーズ「C/C++組込み開発者のためのDoxygen実践ガイド」の第3回です。

第1回：環境構築 — インストールからHTML出力まで
第2回：コメント記法と実践的な記載例
第3回（本記事）：GitHub Actions + GitHub PagesによるCI自動ドキュメント生成

はじめに

第1回・第2回でDoxygen単体の環境構築とコメント記法を解説しました。しかし、ローカルで doxygen Doxyfile を手動実行するだけでは、ドキュメントの更新がメンバーそれぞれの作業に依存してしまいます。

本記事では、mainブランチへのpushをトリガーにDoxygenが自動実行され、GitHub Pagesに最新ドキュメントが公開される仕組みを構築します。一度設定すれば、チームメンバーは意識することなく常に最新のリファレンスを参照できる状態になります。

全体アーキテクチャ

開発者がmainにpush
        ↓
GitHub Actionsがトリガー（buildジョブ）
        ↓
Ubuntu環境でDoxygen実行 → HTMLを生成
        ↓
Pagesアーティファクトとしてアップロード
        ↓
GitHub Actionsがトリガー（deployジョブ）
        ↓
GitHub Pagesで公開（https://<user>.github.io/<repo>/）

前提条件

GitHubリポジトリが作成済みであること
第1回で作成した Doxyfile がリポジトリルートにコミットされていること
リポジトリの Settings → Pages で Source が「GitHub Actions」に設定されていること

1. Doxyfileの出力先を確認する

GitHub Actionsからデプロイしやすいよう、Doxyfileの出力先を固定しておきます。

OUTPUT_DIRECTORY       = ./docs
GENERATE_HTML          = YES
HTML_OUTPUT            = html

この設定だと、HTMLは ./docs/html/ に出力されます。ワークフロー内でこのパスを参照します。

2. GitHub Actionsワークフローの作成

リポジトリに以下のファイルを作成します。

.github/
└── workflows/
    └── doxygen.yml

ワークフローファイル全体

name: Generate Doxygen Documentation

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Install dependencies
      run: |
        sudo apt-get update
        sudo apt-get install -y doxygen graphviz

    - name: Generate documentation
      run: doxygen Doxyfile

    - name: Setup Pages
      uses: actions/configure-pages@v5

    - name: Upload Pages artifact
      uses: actions/upload-pages-artifact@v3
      with:
        path: ./docs/html

  deploy:
    needs: build
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4

各ステップの解説

permissions
最小権限の原則に従い、ジョブレベルで権限を分割しています。build ジョブは contents: read のみ、deploy ジョブに pages: write と id-token: write を付与します。これにより外部コントリビューターのPRで不要な pages: write が有効になることを防ぎます。

concurrency
複数のpushが短時間に重なった際に、デプロイが競合しないよう直列化します。

.nojekyll の扱い
GitHub PagesはデフォルトでJekyllによるビルドを試みます。Doxygenの生成物はそのまま静的HTMLとして公開したいため、.nojekyll を置いてJekyllの処理をスキップします。actions/configure-pages@v5 が .nojekyll を自動生成するため、手動での touch は不要です。

actions/upload-pages-artifact@v3
指定パス（./docs/html）の内容をGitHub Pages用のアーティファクトとしてアップロードします。gh-pagesブランチは使いません。

deploy ジョブ
needs: build で buildジョブの完了を待ってから実行されます。if 条件でmainへのpushのみデプロイが走るようにしており、PRでは build（ドキュメント生成の確認）のみ実行されます。

3. GitHub Pagesの設定

リポジトリの Settings → Pages を開き、以下のように設定します。

項目	設定値
Source	GitHub Actions

「Deploy from a branch」ではなく「GitHub Actions」を選択する点が重要です。これにより、gh-pagesブランチを作らずにActionsのアーティファクトを直接デプロイできます。GitHub Actionsがアーティファクトの保存・転送を担うため、ブランチへのコミットが不要になります。

保存後、ワークフローが初回実行されると https://<user>.github.io/<repo>/ にアクセスできるようになります。

4. 動作確認

pushしてActionsを確認する

mainブランチに何かコミット・プッシュすると、リポジトリの Actions タブにワークフローが表示されます。

git add .github/workflows/doxygen.yml Doxyfile
git commit -m "ci: DoxygenのCI/CD設定を追加"
git push origin main

Actions画面で Generate Doxygen Documentation の build → deploy の両ジョブが緑（✓）になれば成功です。

公開URLを確認する

Settings → Pages に表示されているURLをブラウザで開きます。Doxygenで生成されたHTML（関数一覧・クラス図など）が表示されれば完了です。

以降は、mainへのpushのたびに自動でドキュメントが更新されます。

5. トラブルシューティング

症状	原因と対処
`deploy` ジョブが `skip` になりデプロイされない	`if` 条件を確認。PRイベントではbuildのみ実行される仕様
Pagesにアクセスしても404になる	Settings → Pages の Source が「GitHub Actions」になっているか確認する
`pages: write` 権限エラーが出る	ワークフローの `permissions` ブロックに `pages: write` と `id-token: write` が含まれているか確認する
graphvizのグラフが表示されない	ワークフロー内で `graphviz` がインストールされているか、`HAVE_DOT = YES` がDoxyfileに設定されているか確認する
日本語が文字化けする	ソースファイルがUTF-8で保存されているか確認する

まとめ：シリーズ総括

3回にわたってDoxygenの導入から自動化までを解説しました。

回	内容	得られるもの
第1回	インストール・Doxyfile設定・HTML出力	ローカルでドキュメントを生成できる
第2回	コメント記法・記載例・規約化	チームで統一されたコメントが書ける
第3回（本記事）	GitHub Actions + Pages連携	pushのたびに最新ドキュメントが自動公開される

チーム展開のポイント

Doxygenの定着には技術的な設定より運用ルールの整備が鍵です。以下の3点を最初に決めておくと、導入後のトラブルが減ります。

コーディング規約にコメント記法を明文化する（第2回参照）
レビューチェックリストにDoxygenコメントの項目を加える
生成ドキュメントのURLをチームのWikiやREADMEに記載する（「見る場所がある」と更新モチベーションが維持される）

ドキュメントが「書いたら終わり」ではなく「コードと一緒に育つ」状態を目指してください。

シリーズ一覧

第1回：環境構築 — インストールからHTML出力まで
第2回：コメント記法と実践的な記載例
第3回（本記事）：GitHub Actions + GitHub PagesによるCI自動ドキュメント生成

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up