decisiondecided

agents/methodology を submodule から通常ファイルへ移す

Cloudflare Pages が private submodule を認証なしで clone できずビルドが丸ごと失敗するため、agents/methodology の submodule を廃止し実体を通常ファイルとして追跡する。恒久対応(方法論リポジトリの公開か Cloudflare へのアクセス付与)は owner 判断。

Context

Parlourite Notes は Cloudflare Pages の git 連携で blog.parlourite.com を配信している。2026-10-02 のビルドが、デプロイどころか clone 段階で失敗した。

Submodule 'agents/methodology' (https://github.com/Mitsuki61/agent-methodology.git)
registered for path 'agents/methodology'
fatal: could not read Username for 'https://github.com': No such device or address
fatal: clone of '...' into submodule path 'agents/methodology' failed
Failed to clone 'agents/methodology'. Retry scheduled
...
Failed: error occurred while updating repository submodules

原因は単純である。

  • Cloudflare Pages の clone は git clone --recurse-submodules 相当で、.gitmodules がある限り submodule の fetch を試みる。
  • agent-methodology は private リポジトリ(匿名アクセスは 404。ローカルでは Windows 資格情報マネージャのキャッシュで通っていた)。
  • Cloudflare のビルド環境は資格情報を持たないため fetch に失敗し、clone 全体が失敗する。したがって npm run build には到達しない。

調査の結果、Cloudflare Pages には submodule clone をスキップする設定が存在しない(.gitmodules の ignore = all も効かない)。つまり「private submodule を使いつつ Pages の git 連携でビルドする」経路は存在しない。

一方で、サイトのビルドは agents/ に一切依存しない(astro.config.mjs は src/content/** のみを読む)。落とすべきは配布物ではなく clone の前提条件である。

Decision

agents/methodology の submodule を廃止し、実体を通常ファイルとして本リポジトリで追跡する。

  • 削除: .gitmodules、agents/methodology の gitlink(index mode 160000)
  • 追加: agents/methodology 配下 54 ファイルを mode 100644 で追跡
  • 追加: .gitattributes で agents/methodology/** を LF 固定

.gitattributes を添えたのは、submodule 時代は独立リポジトリの改行設定に委ねていた部分が、通常ファイル化により本リポジトリの core.autocrlf(Windows では true)の影響を受けるようになるため。bash スクリプトの interpreter 行が CRLF 化すると WSL/CI で起動不能になる。

コミット: 7e964eb

検証

確認方法結果
ビルドが通るnpm run build(Supervisor 実行)EXIT:0
Pages の clone が通るgit clone --recurse-submodules file://…(認証プロンプト抑止)EXIT:0
submodule を fetch しないclone 先に .gitmodules が無い / git submodule status が空確認
実体が配られるclone 先の agents/methodology/** が 54 ファイル確認
gitlink が残っていないgit ls-files -s | awk '$1==160000' が空確認

恒久対応の選択肢(owner court)

本決定は「今ビルドを通す」ための vendoring であり、shared リポジトリを各リポジトリへ複製する。方法論は Parlourite と Notes の両リポジトリで同期して使われており、複製はドリフトの温床になる。恒久形は次のいずれかで、いずれも owner の操作を要する。

案内容長所短所
A. 方法論リポジトリを public 化GitHub の visibility を変更submodule を維持できる。両リポジトリが無変更で済む公開の是非は owner 判断
B. Cloudflare にアクセス付与Cloudflare の GitHub App に agent-methodology へのアクセスを許可リポジトリ無変更有効性は未検証。Cloudflare 側の操作
C. vendoring(本決定)実体を各リポジトリで追跡認証依存ゼロ・自己完結方法論更新のたびに手動同期

A か B が成立するなら、本コミットを revert して submodule に戻すのが最も整合的である(C は A/B に対する暫定である)。

Consequences

得るもの

  • Cloudflare Pages のビルドが通る(clone が認証情報に依存しない)
  • 新規 clone に追加手順が要らない(submodule の --init --recursive が不要)

失うもの

  • git submodule update --remote agents/methodology による同期。更新は実体のコピーで行う(手順は Git submodule 運用ガイド — 何がいつ更新されるのか を更新済み)
  • 親 commit が「方法論のどの版を指すか」を SHA で記録する仕組み。以降はツリーの内容そのものが版となる

見直し条件

  • A(public 化)または B(Cloudflare アクセス付与)が実施された → revert して submodule へ戻す
  • 方法論の更新頻度が上がり手動同期が破綻した → A/B の実施を owner へ再提起する

参照