GitHub documentation updateで何が変わる？linkchecker修正とlearn.microsoft.comリンク確認ポイント

「GitHub documentation update: Fix linkchecker by remapping root-relative links to learn.microsoft.com」は、GitHub本体の仕様変更ではなく、MicrosoftDocsのドキュメントリポジトリでリンクチェック用のGitHub Actionsワークフローを修正した更新です。結論から言うと、/entra/... のようなroot-relativeリンクをローカルパスとして誤判定させず、https://learn.microsoft.com/... として検証できるようにする変更です。これにより、CIのリンクチェックで発生していた不要な失敗を減らしつつ、Microsoft Learn上で実際に切れているリンクを検出しやすくなります。対象は主に、GitHub Actionsでドキュメントのリンク検証を運用している管理者、テクニカルライター、開発者です。対象PRは2026年5月19日にマージされ、MicrosoftDocs/microsoft-authentication-library-for-python のリンク検証ワークフローと一部Markdownが更新されています。(GitHub)

GitHubの「Fix linkchecker by remapping root-relative links to learn.microsoft.com」は何が変わったのか

今回の変更は、Microsoft Authentication Library for Python、いわゆるMSAL Python関連ドキュメントのリンクチェックを安定させるためのものです。PR名には「remapping」とありますが、最終的な実装では単にlycheeの--remapオプションを追加しただけではありません。最終差分では、lycheeを実行する前にMarkdown内のroot-relativeリンクをsedで書き換えるステップが追加されています。(GitHub)

具体的には、[text](/path) のようなMarkdownリンクを、CI上で次のような形に変換してからリンクチェッカーに渡します。

- name: Resolve root-relative links for checking
  run: |
    # Convert root-relative markdown links like [text](/path) to [text](https://learn.microsoft.com/path)
    # so lychee can validate them. This only modifies the CI checkout copy.
    find . -name '*.md' -exec sed -i -E 's|\]\(/|\](https://learn.microsoft.com/|g' {} +

このステップにより、たとえば次のようなリンクの扱いが変わります。

項目	変更前	変更後
/entra/... のようなリンク	ローカルファイルパスとして解釈され、解決不能なパスとして失敗しやすい	https://learn.microsoft.com/entra/... として本番サイトに対して検証される
CIの失敗理由	実際のリンク切れではなく、解釈方法の違いで失敗する可能性がある	Microsoft Learn上で到達できるかを確認できる
Markdown本文	ソースファイル自体を恒久的に書き換えるわけではない	CIのチェックアウト環境上で事前変換する
追加修正	空のMarkdownリンクが残る可能性があった	migrate.md の空リンクも修正された

あわせて、msal-python-conceptual/advanced/migrate.md では、空だった[official APIs]()リンクが../getting-started/acquiring-tokens.mdへのリンクに修正されています。リンクチェックの設定だけでなく、実際のドキュメント内にあったリンク不備も同時に解消された形です。(GitHub)

--remapだけではなくsed前処理になった点が重要

今回の更新で注意したいのは、PRの説明では当初「lycheeの引数に--remapを追加する」と説明されていたものの、最終的にはsedによる前処理に変更されている点です。

PR内のコミット履歴では、最初に--remapでroot-relativeリンクをlearn.microsoft.comへ書き換える方針が取られました。その後、正規表現が絶対URL内の/まで拾ってしまい、https://https//...のような壊れたURLを作る問題を避けるため、正規表現をroot-relativeリンクだけに絞る修正が入っています。さらに最終的には、lychee自身のroot-relativeリンク解決で弾かれる前に--remapが介入できないとして、sedでMarkdownを事前変換する方式に置き換えられています。 (GitHub)

実務上はここが最も大事です。自社リポジトリに同じ考え方を取り込む場合、「lycheeに--remapを足せば必ず解決する」と考えるのではなく、リンクチェッカーがどの段階でURLを解決しているかを確認する必要があります。

なぜroot-relativeリンクでリンクチェックが失敗するのか

root-relativeリンクとは、/entra/identity-platform/... のようにドメイン名を省略し、サイトのルートから始まるパスで書かれたリンクです。Webサイト上では自然な書き方ですが、ローカルのMarkdownファイルをCIで検査する場合は解釈が変わります。

Microsoft Learn上では、/entra/... はおおむね「learn.microsoft.com配下のパス」として機能します。一方、GitHub Actions上でMarkdownファイルを直接チェックすると、リンクチェッカーはそれを「ローカルファイルシステム上の絶対パス」や「チェック対象リポジトリ内のルート相対パス」として扱うことがあります。lycheeの公式ドキュメントでも、ローカルファイル内の絶対リンクを扱う場合には--root-dirが必要になること、また--base-urlを指定するとローカルファイル内の相対URLを指定したベースURL上にあるものとして解決できることが説明されています。(Docs)

つまり、問題の本質は「リンクが間違っている」ことではなく、「公開サイト上でのURL解決ルール」と「CI上でのファイル検査ルール」が一致していないことです。

影響範囲：GitHub利用者全員に影響する変更ではない

この更新は、GitHubの全ユーザーに適用されるサービス変更ではありません。影響を受けるのは、同じようなドキュメント運用をしているチームです。

対象	影響
MicrosoftDocsの当該リポジトリ	リンクチェックの誤検出が減り、Microsoft Learn上の実リンクとして検証しやすくなる
GitHub Actionsでlycheeを使っているドキュメント管理者	root-relativeリンクの扱いを見直す参考になる
MarkdownでMicrosoft Learnへのルート相対リンクを書いている開発者	CIで失敗する場合、リンク形式か検証設定の修正が必要になる
アプリケーション開発者	アプリ本体の挙動、GitHub API、MSAL Pythonの実行時動作には基本的に影響しない
GitHub Enterprise管理者	類似ワークフローがある場合、Actionsの権限、外部Actionの固定、リンクチェック対象を確認する価値がある

特に、社内ドキュメントや公開技術文書をGitHub上で管理し、PRごとにリンクチェックを走らせているチームは確認対象です。逆に、GitHubでソースコードだけを管理していて、MarkdownのリンクチェックをCIに組み込んでいない場合、この変更による直接的な対応はほぼ不要です。

管理者・開発者がまず確認すべきポイント

同じ問題が自社リポジトリで起きていないかを確認するには、まずroot-relativeリンクの有無を洗い出します。Markdownが多いリポジトリなら、次のような検索で候補を見つけられます。

rg '\]\(/' -g '*.md'

rgが使えない環境では、次のようにgrepでも確認できます。

grep -RIn '\](/' --include='*.md' .

見つかったリンクについて、次の3点を確認してください。

確認項目	判断基準
その/pathは外部サイトのパスか	Microsoft Learnなど、公開サイトのルートを前提にしているなら変換対象
リポジトリ内のローカルファイルか	/docs/...や/images/...が自サイト内ファイルなら、learn.microsoft.comへ変換してはいけない
コード例や説明文の中に含まれていないか	コードブロック内のサンプルまで機械的に変換すると、意図しない変更になる

この確認をせずにsedで一括変換すると、本来はローカルサイト内の画像やページを指すリンクまで外部URLに変わってしまう可能性があります。

自社リポジトリに取り込む場合の選択肢

今回のPRと同じ課題がある場合でも、必ず同じsedコマンドを使うべきとは限りません。リンクの性質によって、選ぶべき方法が変わります。

方法	向いているケース	注意点
CIでsed前処理する	/entra/...のようなリンクをすべて同じ公開ドメインに向けたい場合	変換対象が広すぎると、ローカルリンクやコード例も変わる
lycheeの--base-urlを使う	ドキュメント全体を特定の公開URL配下として検証したい場合	すべての相対リンクが同じベースURL前提でよいか確認が必要
lycheeの--root-dirを使う	root-relativeリンクがリポジトリ内ファイルを指している場合	外部サイトのパスを検証したい用途には合わない
Markdownを絶対URLに書き換える	公開先が固定で、可搬性より明示性を優先する場合	将来ドメインやパスが変わると修正範囲が広がる
変換スクリプトを自作する	Microsoft Learn以外にも複数ドメインが混在する場合	テストなしで導入すると誤変換に気づきにくい

lychee-actionは、GitHub Actions上でMarkdown、HTML、テキスト内のリンクをチェックするActionで、lychee本体の引数はargsパラメータから渡せます。キャッシュを使って外部サイトへの負荷やレート制限の影響を抑える設定も用意されています。(GitHub)

推奨する展開手順

既存ワークフローに同様の修正を入れる場合は、いきなりmainブランチへ反映するのではなく、次の順序で進めるのが安全です。

手順	作業内容	確認ポイント
事前調査	Markdown内のroot-relativeリンクを検索する	外部サイト向けとローカルファイル向けを分類する
方針決定	sed、--base-url、--root-dir、絶対URL化のどれを使うか決める	変換対象のドメインが1つに絞れるか確認する
検証ブランチ作成	ワークフローだけを変更するPRを作る	ドキュメント本文の変更とCI設定変更を混ぜすぎない
ドライラン	PR上でリンクチェックを実行する	失敗ログが「本当のリンク切れ」か「変換ミス」かを分けて見る
対象外設定	必要に応じて.lycheeignoreや除外設定を調整する	403や429などを安易に許可しすぎない
本番反映	mainへマージし、定期実行の結果も確認する	スケジュール実行とPR実行で結果が変わらないか確認する

今回のPRでは、lychee実行時に--accept=200,429,403,502,503が指定されています。lycheeのデフォルトでは主に100番台の一部と200番台が成功扱いになるため、403や429などを許容する場合は、なぜ許容するのかをチーム内で明文化しておくべきです。許容範囲を広げすぎると、本来検知すべきリンク切れやアクセス制御の問題を見逃す可能性があります。(Docs)

失敗しやすいポイント

正規表現が広すぎるとURLを壊す

PRの途中コミットでは、正規表現が絶対URL内の/まで拾ってしまい、https://https//learn.microsoft.com//github.com/...のような壊れたURLを作る問題が説明されています。root-relativeリンクだけを対象にするには、/を含むすべての文字列ではなく、Markdownリンクの開始パターンに絞る必要があります。 (GitHub)

CIの作業ディレクトリを書き換える影響を見落とす

今回のコメントでは「CIのチェックアウトコピーだけを変更する」とされていますが、同じジョブの後続ステップでドキュメントのビルドや公開をしている場合は注意が必要です。sedで書き換えた後のMarkdownをそのまま成果物に含めると、公開物のリンク形式まで変わる可能性があります。

リンクチェック専用ジョブに分離する、または公開前に再度checkoutするなど、検証用の変換が成果物へ混ざらない設計にしておくと安全です。

実行環境によってsed -iの挙動が違う

PRのワークフローはubuntu-latest上で実行されています。GNU sedを前提にしたsed -i -Eは、macOSのBSD sedやWindows系のセルフホストランナーではそのまま動かない場合があります。セルフホストランナーを使っている組織では、OSごとの差を避けるためにNode.js、Python、PowerShellなどで明示的な変換スクリプトを書く選択肢もあります。

Microsoft Learn向けでない/pathまで変換してしまう

/entra/...はMicrosoft Learnの文脈では自然ですが、/images/logo.pngや/docs/setup.mdのようなリンクは自サイト内の資産を指している可能性があります。すべての/始まりのリンクをlearn.microsoft.comへ向けると、画像、社内ドキュメント、サイト内ナビゲーションが壊れることがあります。

変換前に、少なくとも次の分類をしておくべきです。

リンク例	変換判断
/entra/identity-platform/...	Microsoft Learn向けなら変換候補
/azure/...	Microsoft Learn向けなら変換候補。ただし公開先を確認
/docs/getting-started.md	リポジトリ内ページの可能性があるため要確認
/images/sample.png	画像資産の可能性が高く、機械変換は危険
https://example.com/path	すでに絶対URLのため変換不要

GitHub Actions管理者が見直すべきセキュリティ設定

リンクチェックは軽いCIに見えますが、外部Actionを実行し、リポジトリ内容やトークンにアクセスする点では通常のCI/CDと同じ管理対象です。

今回のワークフローでは、actions/checkout@v3、lycheeverse/lychee-action@master、peter-evans/create-issue-from-file@mainが使われています。自社で同様のワークフローを整備する場合は、@masterや@mainのような可変参照をそのまま使うのではなく、固定バージョンやコミットSHAへの固定を検討してください。GitHubの公式ドキュメントでは、外部Actionを安全に使うための方法として、フル長のコミットSHAへのピン留め、Actionのソースコード監査、トークン権限の制限などが推奨されています。(GitHub Docs)

また、リンクチェックでIssueを自動作成する場合だけissues: writeが必要になります。単にリンクを検証するだけなら、より狭い権限で足りるケースもあります。ワークフローごとに「本当に書き込み権限が必要か」を確認し、不要なcontents: writeや広い権限を残さないことが重要です。

開発者・ドキュメント担当者が守るべき運用ルール

リンクチェックの安定性は、CI設定だけでは決まりません。日々Markdownを書く側のルールも必要です。

まず、Microsoft Learnのような外部公式ドキュメントへリンクする場合は、チーム内で「絶対URLで書くのか」「root-relativeで書くのか」を統一します。Microsoft Learn内での移植性を優先するならroot-relativeリンクは便利ですが、GitHub上のMarkdown単体で検証する場合は今回のような補正が必要になります。

次に、空リンクをPRレビューで見逃さない仕組みを入れます。今回のPRでも[official APIs]()のような空リンクが修正されています。空リンクは見た目では気づきにくいため、リンクチェッカーだけでなく、Markdown lintやレビュー観点にも含めると効果的です。

最後に、リンクチェックの失敗をすぐに除外設定で回避しないことです。403や429は外部サイト側の制限で発生することがありますが、恒久的に成功扱いにすると検知精度が落ちます。除外や許容ステータスを追加する場合は、「一時的な回避」なのか「仕様として許容」なのかをPR説明に残しておくと、後から見直しやすくなります。

今回の更新から取るべき実務上のアクション

今回のGitHub documentation updateは、GitHub本体の新機能ではなく、ドキュメントCIのリンクチェック精度を上げるための修正です。とはいえ、同じ課題は多くのドキュメントリポジトリで起こり得ます。

まず、自社リポジトリで/始まりのMarkdownリンクを検索してください。次に、それらが公開サイト向けなのか、リポジトリ内ファイル向けなのかを分類します。そのうえで、Microsoft Learnのような特定ドメインへ解決すべきリンクだけを、CI上で安全に変換する仕組みを検討します。

特に重要なのは、--remap、sed、--base-url、--root-dirを目的に応じて使い分けることです。機械的に今回のコマンドをコピーするのではなく、「自分たちのroot-relativeリンクは、どのサイトのルートを前提にしているのか」を確認してから展開すれば、リンクチェックの誤検知を減らしながら、実際のリンク切れを早い段階で発見できるようになります。