はじめに

GitHub Pages は設定が簡単で無料という利点がある一方、Actions 経由のデプロイは「遅い」と感じられることがある。本記事では、GitHub Pages の公式 Actions を前提に、どこまで高速化でき、どこから先が構造的な限界なのかを整理する。結論だけでなく、なぜそうなるのかという設計理由も含めて解説する。

GitHub Actions における「遅さ」の正体

Pages デプロイの処理時間は、ビルド計算よりも I/O に強く依存する。具体的には、artifact の圧縮、アップロード、Pages 側での検証と展開が支配的である。ビルド工程が軽量な場合、YAML の最適化で削れる余地は限定的になる。

そのため、高速化の基本軸は「送る量を減らす」「無駄に workflow を起動しない」に集約される。CPU 使用率や並列化を意識しても、効果はほとんどない。

paths / paths-ignore の役割と誤解

push.triggers の paths や paths-ignore は、「workflow を起動するかどうか」を決める条件であり、デプロイ対象のファイル量には一切影響しない。ignore を多く書いたから処理が遅くなる、という因果関係は存在しない。

一方で、paths-ignore は論理的に分かりにくく、想定外に workflow が走る原因になりやすい。公開対象が明確な場合は、例外を列挙するより paths で主語を限定した方が挙動が安定する。

upload-pages-artifact が必須である理由

GitHub Pages の deploy-pages アクションは、直前にアップロードされた Pages 用 artifact のみを入力として動作する。push の paths 設定で対象を絞っていても、artifact を省略することはできない。

これは、イベント条件とデータフローを明確に分離する設計思想によるものだ。Pages は「どのファイルを公開するか」を暗黙に推論せず、利用者が明示的に指定することを前提としている。

docs と dist の両方が必要なケースの整理

docs/index.html がクエリ文字列を使って dist 配下の md を動的に fetch する構成では、docs と dist はどちらも最終成果物である。この場合、入力と出力を分離するモデルは成立しない。

ただし、upload-pages-artifact は単一パスしか指定できないため、公開用ディレクトリ（例: public）を作成し、その配下に docs と dist をまとめる必要がある。Pages は「単一ルートを丸ごと公開する」モデルしか持たないためである。

fetch-depth: 1 の意味と安全性

actions/checkout の fetch-depth: 1 は、「現在の HEAD コミットのみを取得する」設定であり、直前の履歴は含まれない。git diff や履歴依存の処理はできなくなるが、静的サイト生成や Pages デプロイでは問題にならない。

push イベントの paths 判定は checkout より前に行われるため、fetch-depth を浅くしてもトリガー条件が壊れることはない。履歴を使わない限り、純粋な最適化と考えてよい。

id-token: write と GITHUB_TOKEN の関係

id-token: write は、OIDC を用いて「この workflow が正規のものだ」と証明するための権限である。actions/deploy-pages@v4 は、この OIDC トークンを用いて Pages 側に認証する。

過去には GITHUB_TOKEN だけで動作する構成も存在したが、現在の公式構成では id-token が前提となっている。これは権限を絞り、短命な認証情報を使うためのセキュリティ設計の変更である。

どこまで高速化できるのかという結論

checkout の shallow 化、artifact 対象の限定、paths による起動抑制まで行うと、残る時間は GitHub Pages 側の固定コストになる。ここから先は YAML の工夫では削れない。

さらなる短縮を狙う場合、送信データそのものを減らす、デプロイ頻度を下げる、あるいは差分デプロイ対応の別サービスを使う必要がある。GitHub Pages を使う限り、現在の構成は実質的に最速に近い。

おわりに

GitHub Pages のデプロイが遅く感じられる場合、多くは設定ミスではなく設計上の限界に達している。本記事で整理した責務分離と制約を理解すれば、無意味な最適化を避け、納得感のある構成を選択できるはずである。