GitHub Wikiの管理が面倒？Actionsで自動同期する実践手順

ども！最近 GitHub Wiki の管理に頭を悩ませている龍ちゃんです。

既製アクション 1 本と YAML 30 行で、docs/wiki/ を GitHub Wiki に自動同期できる仕組みを作ったので共有しますね。

皆さん、GitHub Wiki 使っていますか？

複数のドキュメントを参照したいときはすごく便利なんですが、管理が面倒だったりしますよね。Wiki の情報って完全に人間向けのコンテキスト情報で、あった方がいいのはわかっているんですけど、そんな作業は後回しになりがちで。

最近、AI にドキュメント作成をやらせているんですが、そうすると「人間しか読まないコンテキスト情報をどう管理して、どこに置くべきか？」って悩むんですよね。そんなときに Wiki。でも管理にはあまりコストをかけたくない。同じ悩みがあったので、解決方法を見つけて書いておきますね。

今回の内容です。

GitHub Wiki の「惜しい」ポイントと、docs/ との両立方法
GitHub Wiki の正体（独立した Git リポジトリ）
docs/wiki/ → GitHub Actions → Wiki の構成とワークフロー
実機検証で踏んだ罠 5 選
Wiki 整理を AI Agent Skill に任せるアイデア

それぞれ順番に解説していきますね。

1 GitHub Wiki の「惜しい」ところ
2 GitHub Wiki の正体: 独立した Git リポジトリ
3 構成: docs/wiki/ → GitHub Actions → Wiki
4 実装ステップ: 4つの作業で完成
5 実機検証で踏んだ罠 5 選
6 さらに一歩: Wiki 整理用 Agent Skill を作る
7 おまけ: Mermaid も普通に使える
8 整理すると
9 まとめ
10 参考リンク

GitHub Wiki の「惜しい」ところ

GitHub Wiki は手軽で閲覧性も高いんですよね。ページをリスト表示できて、サイドバーで構造化できて、非エンジニアにも見せやすい。でも、使っていると管理面でちょっと不満が出てきます。

よくある不満点はこのあたりです。

Web UI でしか編集できない（と思われがち） → ローカルで書けない、差分もわかりにくい
PR レビューに乗らない → 誰かが勝手に書き換えても気づけない
コードとドキュメントのバージョンが連動しない → リリースタイミングでドキュメントが古いまま
AI ツール（Claude Code 等）から直接アクセスしにくい → docs/ は読めても Wiki は別管理

結果として「Wiki やめて docs/ だけにしよう」という判断をするチームも多いんですが、Wiki UI の閲覧性は捨てがたいんですよね。

実は両方活かす方法があります。docs/wiki/ に Markdown を書いて、CI/CD で Wiki に自動同期する方法です。

以前、HTMLで保存してる奴、全員Markdownにしろという記事でも書いたんですが、AI 向けに最適化するなら Markdown で Git 管理が基本です。Wiki も同じ考え方で管理できるんですね。

GitHub Wiki の正体: 独立した Git リポジトリ

これが面白くて、GitHub Wiki の裏側には REPO.wiki.git という独立した Git リポジトリがいるんですよね。なので以下のコマンドで普通に clone できます。

git clone https://github.com/OWNER/REPO.wiki.git

実は GitHub CLI のマニュアルを見ても Wiki コマンドはないし、REST API にも専用エンドポイントはないんですが、Git 操作はできます。つまり CI/CD に乗せられるんですね。

構成: docs/wiki/ → GitHub Actions → Wiki

構成はこんな感じです。

使っているのはこのあたりです。

項目	内容
使用 Action	`Andrew-Chen-Wang/github-wiki-action@v4`
認証	`GITHUB_TOKEN` + `permissions: contents: write`（PAT 不要）
実行時間	10〜24秒

Zenn で docs/ から Wiki への自動同期を Node.js で実装している記事もあって、こちらはかなり丁寧に作り込まれています。今回の記事では既製アクション 1 つでサクッと完結する方法を紹介しますね。

Claude Code設計術：AIフレンドリーなドキュメント管理で書いた「GitHub に情報を集約する」設計思想の延長線上にある話ですね。Wiki もその一部に組み込んでしまう感じです。

実装ステップ: 4つの作業で完成

ステップ 1: Wiki の初期化（1分・手動）

まず GitHub リポジトリの Settings > Features で Wiki が有効になっているか確認します。

確認できたら Wiki タブを開いて「Create the first page」で初期ページを作ります。

内容は何でも OK です。あとで同期したときに上書きされます。ここを飛ばすと .wiki.git が存在しない状態になって、後で Actions が失敗するので注意です。

ステップ 2: docs/wiki/ にドキュメントを配置

ディレクトリ構成はこんな感じです。

docs/wiki/
├── Home.md                      # トップページ（必須）
├── _Sidebar.md                  # サイドバー
├── _Footer.md                   # フッター
├── Guide-Getting-Started.md     # プレフィックス命名でフラット管理
├── Guide-Configuration.md
├── Reference-API.md
└── images/
    └── architecture.png         # [[images/architecture.png]] で参照

ファイル命名のポイントをまとめておくと、

ダッシュ - 区切りにする（Wiki 表示でスペースに変換される）
サブディレクトリは使えるが、Wiki の Pages 一覧ではフラット表示になる
同名ファイルが異なるサブディレクトリにあると衝突するので注意
プレフィックスで擬似階層を表現するのが安全（Guide-、Reference- 等）

ぶっちゃけ、サブディレクトリが必要なほど分量が多い Wiki はつらいんですよね。Wiki 側の Pages 一覧はフラットに並ぶだけですし、Web UI でページタイトルにスラッシュ / を入れても自動でハイフンに変換されるので子ページも作れません。

フラットで管理できる程度にまとめておくのが、Wiki としてはちょうどいい粒度だと思います。

ちなみにサブディレクトリごとに独自の _Sidebar.md を置くと、そのフォルダ配下のページでは別のサイドバーが表示されます。どうしても階層が必要な場合はこれで擬似的に対応できますね。

ステップ 3: GitHub Actions ワークフローを追加

以下を .github/workflows/wiki-sync.yml にコピペするだけです。

name: Sync docs/wiki to GitHub Wiki

on:
  push:
    branches: [main]
    paths:
      - 'docs/wiki/**'
      - '.github/workflows/wiki-sync.yml'
  workflow_dispatch:

permissions:
  contents: write

jobs:
  sync-wiki:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Sync to Wiki
        uses: Andrew-Chen-Wang/github-wiki-action@v4
        with:
          path: docs/wiki/
          strategy: clone
          preprocess: false
          disable-empty-commits: true
          commit-message: "wiki: sync from ${{ github.sha }}"

各設定のポイントです。

設定	内容
`paths: docs/wiki/**`	docs/wiki/ の変更時のみ発火（他の変更では動かない）
`permissions: contents: write`	GITHUB_TOKEN 認証（PAT 不要）
`strategy: clone`	差分同期（Wiki の編集履歴を保持）
`disable-empty-commits: true`	変更なし時の空コミット防止
`workflow_dispatch`	手動実行も可能

ステップ 4: push → 自動同期を確認

main に push するだけで Wiki に反映されます。Actions タブで実行結果を確認して（10〜24秒で完了します）、Wiki タブでページ表示を目視確認すれば OK です。

実機検証で踏んだ罠 5 選

実際に検証してみると地味にハマる箇所がいくつかあったんですよね。他ではあまり書かれていないと思うので、「何が起きたか → なぜか → どう直したか」で共有しておきます。

罠 1: Wiki 記法 `[[A|B]]` のパイプが逆

[[Guide-Getting-Started|Getting Started]] と書くと、リンク先が「Getting Started」というページ名で解釈されるんですよね。そのページは存在しないので赤リンクになります。

HTML で確認するとこうなっていました。

<a class="internal absent" href="/wiki/Getting-Started">

整理するとこうなります。

記法	リンク先	結果
`[[Guide-Getting-Started\|Getting Started]]`	Getting-Started	❌ 存在しないページ → 赤リンク
`[[Guide-Getting-Started]]`	Guide-Getting-Started	✅ 正常リンク

対策はパイプなしの [[Guide-Getting-Started]] にするだけです。表示は自動でスペース区切りに変換されます。

罠 2: 画像は Wiki 添付記法 `[[images/xxx.png]]` 一択

Markdown の ![alt](images/xxx.png) を使うと、ページによっては「Could not find version “images”」エラーが出ることがあります。raw URL（wiki 本体どちらも）だと表示されないケースがありました。

安定して表示されるのは Wiki 添付記法の [[images/xxx.png]] だけでした。画像参照はこれ一択と覚えておくといいですね。

罠 3: ファイル名のダッシュ → ページ名でスペースに変換

Guide-Getting-Started.md というファイルは、Wiki では「Guide Getting Started」というページタイトルになります。

整理するとこういう関係です。

項目	値
ファイル名	`Guide-Getting-Started.md`
ページタイトル表示	Guide Getting Started
Wiki 記法での参照	`[[Guide-Getting-Started]]`

「ファイル名 = Wiki 記法での参照名」と覚えておくとすっきりします。

罠 4: サブディレクトリの同名ファイルは衝突する

Wiki の名前空間はフラットなんですよね。サブディレクトリ自体は使えるんですが、guide/page.md と reference/page.md を両方置くと同じ page として衝突します。Pages 一覧にも 1 つしか出てこないです。

サブディレクトリを使う場合はファイル名をユニークにするか、プレフィックス命名でフラット管理するのが安全ですね。

罠 5: Wiki 未初期化だと Actions が失敗する

Wiki タブで 1 ページも作っていないと .wiki.git が存在しない状態になっています。Actions が push 先を見つけられずエラーになるんですね。

ステップ 1 で書いた「手動で 1 ページ作る」というのはこれを回避するためです。内容は何でも OK なので、1 分で終わります。

さらに一歩: Wiki 整理用 Agent Skill を作る

この 5 つの罠、正直僕も全部覚えてられないんですよね。なので AI の Agent Skill に組み込んでしまって、罠の回避も Wiki 整理もまるごと任せるようにしています。

この記事自体を Skill の参考資料として読み込ませれば、AI が知見を活かして動いてくれるんですよね。例えばこんな使い方ができます。

「この機能の Wiki ページを作って」→ 正しい命名・記法で docs/wiki/ に作成
「Sidebar を更新して」→ 新規ページを反映した _Sidebar.md を生成
「このドキュメントを Wiki 用に整理して」→ フラット構成 + Wiki 記法に変換

画像は [[images/xxx.png]]、パイプ記法は使わない、ファイル名はプレフィックス命名 — この辺を全部 AI が自動でやってくれる状態にしておくと、あとは push するだけで Wiki に反映されます。人間はレビューだけですね。

例えば Claude Code の Skill 参考資料にはこんな感じで書いておきます。

# Wiki 記法ルール

## ページリンク
- パイプ記法 [[A|B]] は使わない
- ファイル名そのままで参照: [[Guide-Getting-Started]]

## 画像
- Wiki 添付記法を使う: [[images/xxx.png]]
- Markdown の ![alt](path) は使わない

## ファイル命名
- ダッシュ区切り: Guide-Getting-Started.md
- プレフィックスで擬似階層: Guide-, Reference- 等
- サブディレクトリの同名ファイルは衝突するので注意

## 配置先
- docs/wiki/ に配置
- push するだけで GitHub Actions 経由で Wiki に同期される

これを Skill の references に入れておけば、「Wiki ページを作って」と言うだけで AI がルールに従って docs/wiki/ にファイルを作ってくれます。

おまけ: Mermaid も普通に使える

GitHub Wiki は Mermaid をネイティブレンダリングしてくれます。実際に試してみたら、フローチャート・シーケンス図・クラス図すべて問題なく表示されました。

docs/wiki/ に書いた Mermaid がそのまま Wiki で図表として表示されるので、ドキュメントの表現力がぐっと上がりますね。

整理すると

ここまでの話をまとめるとこんな感じです。

docs/ で一元管理 → PR レビューに乗る、バージョン管理される
AI が docs/ を直接読み書き → push するだけで Wiki にも反映
Wiki UI は残る → 非エンジニアや外部向けの閲覧用として活用

以前の記事でも書いてきた「Markdown にしろ」→「GitHub に集約しろ」という流れの続きで、「Wiki も docs/ から同期しろ」というのが今回の話です。情報の一元化が AI 協業の基盤になるんですよね。

コラム: 既存 Wiki からの移行

すでに Wiki にページがある方向けの移行手順も書いておきます。

git clone https://github.com/OWNER/REPO.wiki.git で既存 Wiki をローカルにダウンロード
メインリポジトリに `docs/wiki/` を作成してファイルを移す
AI（Claude Code 等）を使って整理する
- サブディレクトリをフラット化してプレフィックス命名に変換
- 画像参照を Wiki 添付記法（`[[images/xxx.png]]`）に統一
- `_Sidebar.md` を再生成
ワークフローを追加して push → 同期開始

ステップ 3 は手作業でやると面倒なんですが、AI に任せると一瞬ですね。