Azure DevOps の Wiki とは|プロジェクト Wiki とコード Wiki・Markdown・git での編集・ブランチ保護を実機で検証(DevOps 編 2)

DevOps

はじめに

DevOps 編の 2 回目は、Azure DevOps の Wiki とドキュメント。
Wiki の 2 つの種類(プロジェクト Wiki とコード Wiki)、使える Markdown、中身が Git であることを押さえたうえで、実際に Wiki を作り、git で編集し、ドキュメントのフォルダーを Wiki として公開し、ブランチ ポリシーで保護するところまで試す。
※2026年11月時点の情報です。

前回:Azure Boards とは

Azure Boards とは|プロセスの選び方・エリアとスプリント・WIP 制限・利害関係者を実機で検証(DevOps 編 1)
Azure Boards の仕様と使い方を整理。プロセスの選び方、エリアとスプリント、かんばんの WIP 制限、キャパシティ、継承プロセス、利害関係者のアクセスを実機で確かめた。

Wiki、README、Markdown の全体像

Azure DevOps では、プロジェクトの情報を Markdown で書いて共有する。
書く場所は、プロジェクト Wiki、コード Wiki、リポジトリやプロジェクトの README、ダッシュボードの Markdown ウィジェット。
Wiki は 2 種類あり、どちらも中身は Git リポジトリに置かれた Markdown ファイル。

Azure DevOps の 2 種類の Wiki
項目プロジェクト Wikiコード Wiki
作り方Wiki の画面で「Create project wiki」Wiki の画面で「Publish code as wiki」。
リポジトリ、ブランチ、フォルダーを選ぶ
置き場所専用のリポジトリ(<プロジェクト名>.wiki)既存のリポジトリの中のフォルダー
編集Wiki の画面で追加・編集する。git clone して手元で編集してもよいリポジトリのファイルとして編集する(Wiki の画面からはリポジトリでの編集に進む)
向いているものチームの手順、議事録、ナレッジコードと一緒にバージョン管理したい設計書や API の説明。
プル要求でレビューしてから反映できる

GitHub にも README と Wiki がある。
GitHub の README はリポジトリを開いた人が最初に見るもので、Wiki は長いドキュメント向け。
GitHub の Wiki も Markdown で書け、Mermaid などの図や数式を入れられる。

項目Azure DevOpsGitHub
READMEリポジトリごと、プロジェクトごとに置ける.github、ルート、docs の順に探して表示する。
500 KiB を超える部分は切り捨て
Wikiプロジェクト Wiki とコード Wikiリポジトリごとの Wiki。
ファイル数 5,000 のソフト制限があり、大きいものは GitHub Pages を勧めている
図Mermaid(::: mermaid と “`mermaid の 2 つの書き方)Mermaid、GeoJSON、TopoJSON、ASCII STL

公式ドキュメント:
Wiki、README、Markdown について | Microsoft Learn
プロビジョニングされた Wiki とコード Wiki として発行された Wiki | Microsoft Learn
リポジトリの README ファイルについて – GitHub Docs
ウィキについて – GitHub Docs
ダイアグラムの作成 – GitHub Docs

Markdown で使えるもの

Azure DevOps の Wiki では、標準の Markdown に加えて次のものが使える。

機能書き方ポイント
目次[[_TOC_]]ページの見出しから目次を作る
Mermaid の図::: mermaid で始めて ::: で閉じる(または “`mermaid のコード ブロック)フローチャート、シーケンス図、ガント チャートなど
数式$…$(インライン)、$$…$$(ブロック)KaTeX の記法
作業項目へのリンク# と作業項目の ID入力すると候補が出て、選ぶと作業項目のカードとして表示される。
色コードなどで # を使うときは \# にする
機能書き方ポイント
メンション@ と人やグループユーザーやグループをメンションする
折りたたみ<details> と <summary>HTML のタグでセクションを折りたためる
添付画像やファイルを添付し、リンクで参照する添付は .attachments フォルダーに置かれる
[[_TOC_]]

## 構成
::: mermaid
graph LR
  U[利用者] --> W[Web]
  W --> A[検索 API]
  A --> D[(DB)]
:::

## 関連する作業項目
- 決済 #5

数式:$c = \sqrt{a^2 + b^2}$

![構成図](/.attachments/board-setup.png)

公式ドキュメント:Azure DevOpsで Markdown を使用する | Microsoft Learn

Wiki の中身は Git

Wiki のページは、Git リポジトリの中の Markdown ファイルとして保存される。
Wiki の画面で編集しても、git clone して手元で編集して push しても同じリポジトリが変わる。

ファイル・フォルダー役割
ページ名.md1 ページ 1 ファイル。
ファイル名がページのタイトルになる(ファイル名のハイフンはタイトルでは空白になる)
ページ名のフォルダーサブページを入れる。フォルダー名は親のページ名と同じ
.orderそのフォルダーのページの並び順。1 行に 1 ページ名
.attachmentsWiki で使う添付ファイル
ファイル・フォルダー役割
ブランチプロジェクト Wiki のリポジトリの既定ブランチ(公式の説明では wikiMain)。
ほかのリポジトリと同じようにブランチ ポリシーを付けられる
制限内容
ページのファイル最大 18 MB
添付ファイル最大 19 MB
ファイル名スラッシュ(/)、バックスラッシュ(\)、ハッシュ(#)は使えない。
先頭と末尾にピリオドは置けない

公式ドキュメント:
Git の Wiki ファイルとフォルダー構造 | Microsoft Learn
Wiki コンテンツをオフラインで複製および更新する | Microsoft Learn
Wiki ページの追加と編集 | Microsoft Learn

アクセス許可と検索

Wiki の権限は、中身を置いている Git リポジトリのセキュリティで決まる。
既定では、共同作成者(Contributors)のメンバーが Wiki を読み書きできる。

操作既定で許可されている人
プロジェクト Wiki を見る利害関係者、閲覧者、共同作成者、チーム管理者、プロジェクト管理者
Wiki を作る(プロビジョニング)プロジェクト管理者
Wiki のページを編集する共同作成者(基になるリポジトリへの書き込み権限)

Wiki の検索では、プロジェクト Wiki とコード Wiki をまとめて探せる。
作ったばかりの Wiki は、索引ができるまで検索結果に出ない。

公式ドキュメント:
Wiki とコラボレーション ツールのアクセス許可を管理する | Microsoft Learn
検索の使用を開始する | Microsoft Learn

やってみる

今回の構成と実施すること

今回の構成
手順実施すること確かめること
①プロジェクト Wiki を作り、ホームに目次、Mermaid、数式、作業項目のリンクを書くMarkdown がどう表示されるか
②git clone してページ、サブページ、.order、添付を足し、push する手元の変更が Wiki の画面に反映されるか
③リポジトリの docs フォルダーをコード Wiki として公開するブランチ選択付きの Wiki になる
④Wiki を検索する2 つの Wiki がまとめて検索される
手順実施すること確かめること
⑤Wiki のブランチにブランチ ポリシーを付けるgit push と Wiki 画面の保存が止まる

① プロジェクト Wiki を作る

プロジェクトの「Overview」⇒「Wiki」を開く。

Wiki の作成
番号項目説明
1Create project wiki / Publish code as wikiプロジェクト Wiki を作るか、リポジトリのフォルダーをコード Wiki として公開するか

「Create project wiki」を選ぶとエディターが開く。
左に Markdown、右にプレビューが出る。

Wiki のエディター
番号項目説明
1ツール バー書式、リンク、表、作業項目(#)、添付、Mermaid の図の挿入など
2目次[[_TOC_]] で見出しの一覧ができる
3Mermaidプレビューでは「Load diagram」で図を読み込む

保存したページを表示した。

ホームの表示
番号項目説明
1目次見出しへのリンクになる
2#4、#6全角の「:」の直後に書いたので、作業項目へのリンクにならなかった(実機でつまずいた点を参照)
3Mermaid の図graph LR で書いた流れが図になった
4数式\text{…} の中に日本語を入れたため、描画されずに文字のまま出た

② git clone して手元で編集する

Wiki のリポジトリを git clone すると、ブランチは wikiMaster で、中身は .gitignore、.order(中身は「ホーム」)、ホーム.md だった。
公式の説明では既定のブランチは wikiMain となっているが、今回作った Wiki では wikiMaster だった。
運用手順.md、サブページ用の 運用手順 フォルダーと 障害対応.md、それぞれの .order、.attachments の画像を足して push した。

git clone https://dev.azure.com/<組織>/<プロジェクト>/_git/<プロジェクト>.wiki
cd <プロジェクト>.wiki
git branch            # * wikiMaster

# ページとサブページ、並び順、添付を追加
# 運用手順.md
# 運用手順/障害対応.md
# .order(ホーム、運用手順)と 運用手順/.order(障害対応)
# .attachments/board-setup.png

git add -A
git commit -m "運用手順のページを追加"
git push origin wikiMaster
push したページ
番号項目説明
1ページのツリー.order の順に「ホーム」「運用手順」が並び、運用手順の下に「障害対応」が入った
2#7これも全角の「:」の直後なのでリンクにならなかった
3数式英数字だけの数式は、インラインもブロックも描画された

Wiki の画面で、半角スペースのあとに # と番号を入れると、作業項目の候補が出た。

作業項目の候補
番号項目説明
1候補「User Story 5: クレジットカードで支払える」が出る
2プレビュー作業項目の番号、タイトル、状態のカードとして表示される

※作業項目の側の「リンク」(関係)には、この Wiki ページは追加されなかった(REST API で確認)。

添付の画像は、Markdown から /.attachments/ のパスで参照すると表示された。

添付の画像

③ docs フォルダーをコード Wiki として公開する

リポジトリ boards-demo に README.md と docs フォルダー(はじめに.md、api.md、api/検索.md)を push した。
Wiki の一覧のメニューから「Publish code as wiki」を選ぶ。

コードを Wiki として公開
番号項目説明
1Repository公開するリポジトリ
2Branch公開するブランチ(今回は main)
3FolderWiki にするフォルダー(今回は /docs)
4Wiki nameWiki の名前(今回は boards-demo-docs)
公開したコード Wiki
番号項目説明
1ブランチコード Wiki にはブランチの選択欄が付く
2ページ.order を置いていないので、ファイル名の順(api > 検索、はじめに)に並んだ

④ Wiki を検索する

Wiki を作った直後は、索引の作成中で結果が出なかった。

索引の作成中

Wiki を作ってから 8 分ほどで、検索の結果が出た。

「障害」の検索
番号項目説明
1結果プロジェクト Wiki の 運用手順 > 障害対応.md が見つかった
「API」の検索
番号項目説明
1コード Wikiboards-demo-docs の docs/api.md
2プロジェクト Wikiboards-demo.wiki のホーム.md。
2 つの Wiki がまとめて検索された

⑤ Wiki のブランチを保護する

Wiki のリポジトリはリポジトリの一覧には出ないが、ブランチの画面は URL(_git/<プロジェクト>.wiki/branches)で開けた。

Wiki のリポジトリのブランチ
番号項目説明
1wikiMaster既定(Default)のブランチ

行のメニューの「Branch policies」はプロジェクト設定のリポジトリの一覧に進むだけで、Wiki のリポジトリは一覧になかった。
そこで、REST API で wikiMaster に「最小レビュー担当者数 1」のポリシーを付けた。
この状態で手元から push すると、拒否された。

 ! [remote rejected] wikiMaster -> wikiMaster (TF402455: Pushes to this branch are not permitted; you must use a pull request to update this branch.)

Wiki の画面でページを直して保存しても、止められた。

Wiki の画面からの保存も止まる
番号項目説明
1メッセージ「Pushes to this branch is not permitted. Please continue with ‘Edit in Repos’ and use a pull request to update this branch.」

ブランチ ポリシーを付けると、Wiki の画面からも直接は書けず、プル要求での更新が必要になる。
なお、Wiki を作ったときに、Wiki のリポジトリには「ファイル サイズの制限」(25 MiB、超えると拒否)のポリシーが自動で付いていた(REST API で確認)。

実機でつまずいた点

#番号が作業項目のリンクにならない

「検索:#4」のように、全角の「:」の直後に # と番号を書くと、作業項目のリンクにならず、ただの文字のまま表示された。
エディターでも、全角の文字の直後では作業項目の候補が出なかった。
# の前に半角スペースを入れると候補が出て、作業項目のカードとして表示された。
日本語の文の中で作業項目を参照するときは、# の前に半角スペースを入れる。

半角スペースのあとなら候補が出る

数式の \text に日本語を入れると描画されない

$\text{月額} = \text{時間単価} \times 730$ のように \text の中に日本語を入れた数式は、描画されずに記号のまま表示された。
同じページでも、英数字だけの数式($c = \sqrt{a^2 + b^2}$ など)は描画された。
数式の中は英数字にし、日本語の説明は数式の外に書く。

日本語を入れた数式

We are not able to show results because one or more projects in your organization are still being indexed

Wiki を作った直後に検索すると、このメッセージが出て結果が 0 件だった。
画面には「2 時間たっても結果が出なければ連絡を」と出ていて、今回は Wiki を作ってから 8 分ほどで検索できるようになった。
新しい Wiki やプロジェクトは、しばらくしてから検索する。

索引の作成中

推奨構成

項目推奨
使い分けチームの手順やナレッジはプロジェクト Wiki、コードと一緒に版を管理したい設計書や API の説明はコード Wiki
レビュー大事な Wiki はブランチ ポリシーで保護し、プル要求で更新する
構成.order で並び順を決め、添付は .attachments に置く。
サブページはフォルダーで分ける
書き方目次と Mermaid の図を使う。
作業項目は # の前に半角スペースを入れてリンクする

注意事項

項目内容
ブランチ名公式の説明は wikiMain だが、今回作った Wiki は wikiMaster だった。
git で扱う前にブランチ名を確かめる
サイズページのファイルは最大 18 MB、添付は最大 19 MB
Wiki のリポジトリリポジトリの一覧に出ないため、ブランチ ポリシーはポータルから設定できなかった(REST API で設定した)
権限Wiki の権限は基になる Git リポジトリのセキュリティで決まる
項目内容
検索作った直後は索引の作成中で結果が出ない
数式\text の中の日本語は描画されなかった

公式ドキュメント:
Git の Wiki ファイルとフォルダー構造 | Microsoft Learn
Wiki ページの追加と編集 | Microsoft Learn
Wiki とコラボレーション ツールのアクセス許可を管理する | Microsoft Learn

まとめ

・Azure DevOps の Wiki は、専用リポジトリのプロジェクト Wiki と、リポジトリのフォルダーを公開するコード Wiki の 2 種類で、どちらも中身は Git の Markdown。
・Markdown では目次、Mermaid、数式、作業項目のリンク、折りたたみ、添付が使え、作業項目のリンクは # の前に半角スペースが要った。
・git clone して .order や .attachments を含めて編集でき、プロジェクト Wiki の既定のブランチは wikiMaster だった。
・Wiki のブランチにポリシーを付けると、git push も Wiki 画面の保存も止まり、プル要求での更新になる。

次回:Azure Repos と Git

Azure Repos とは|ブランチ戦略・プル要求・マージの種類・ブランチ ポリシーを実機で検証(DevOps 編 3)
Azure Repos を整理。Git と TFVC、ブランチ戦略、プル要求とマージの 4 種類、ブランチ ポリシーを押さえ、main の保護からスカッシュ、Revert まで実機で確かめた。

コメント

タイトルとURLをコピーしました