GitHub ActionsでGitHub Pagesを本番デプロイしている場合、今回の「Revert Pages actions v4->v5 in release.yml to fix broken prod deploy」は、Pages向けActionをv5からv4へ戻し、本番サイトが壊れる問題を回避するための修正です。対象は主に、actions/upload-pages-artifact と actions/deploy-pages を使ってGitHub Pagesへ静的サイトを公開している管理者・開発者です。
ポイントは、ワークフロー上は成功しているように見えても、公開サイトでは期待したビルド成果物ではなく、README.mdなど別の内容が表示される可能性があることです。CIのチェックがグリーンでも「本番表示が正しい」とは限らないため、GitHub Pagesのデプロイ後確認、Actionのバージョン整合性、Pagesの公開元設定をセットで見直す必要があります。(GitHub)
GitHub Actionsの「Revert Pages actions v4->v5」は何が変わったのか
今回の変更は、Azureのawesome-azdリポジトリにあるrelease.ymlで、GitHub Pages向けの2つのActionをv5からv4へ戻すものです。
具体的には、次のような変更です。
| 対象Action | 変更前 | 変更後 | 目的 |
|---|---|---|---|
actions/upload-pages-artifact | v5.0.0 | v4.0.0 | Pages用アーティファクトのアップロード方式を安定版へ戻す |
actions/deploy-pages | v5.0.0 | v4.0.5 | GitHub Pagesへのデプロイ処理を互換性のある構成へ戻す |
PRでは、これらのActionがSHAピン留めされた状態のままv4へ戻されたと説明されています。一方で、actions/checkoutやactions/setup-nodeなど、他のAction更新は維持されています。つまり、今回の修正は「ワークフロー全体を巻き戻す」のではなく、Pagesデプロイに関係するActionだけを狙って戻すロールバックです。(GitHub)
なぜv5からv4へ戻す必要があったのか
背景には、直前のPRで実施されたGitHub Actionsのモダナイゼーションがあります。PR #876では、actions/upload-pages-artifactとactions/deploy-pagesがv5.0.0へ更新されました。レビュー時点でも、テスト用ワークフローがビルドとテストまでは確認している一方で、実際のデプロイ経路までは検証していない点が指摘されています。(GitHub)
その後、本番サイトではDocusaurusで生成されたギャラリーではなく、Jekyllでレンダリングされた素のREADME.mdが表示される状態になりました。重要なのは、Release Awesome Azdワークフロー自体は成功扱いだったことです。(GitHub)
この種のトラブルは、GitHub Actions運用で特に見落とされやすい問題です。ビルドログ、ジョブの終了ステータス、GitHub Pagesの実表示は、それぞれ別の観点で確認しなければなりません。
今回の問題で起きた流れ
| 段階 | 状態 | 見落としやすい点 |
|---|---|---|
| Action更新 | Pages関連Actionをv5へ更新 | メジャーバージョン更新だが、ビルド・テストだけでは検出できない |
| ワークフロー実行 | アップロード・デプロイ手順は成功扱い | Actionsの成功表示だけでは本番表示を保証できない |
| 公開サイト | DocusaurusギャラリーではなくREADME.mdが表示 | ユーザー影響は本番サイトで初めて分かる |
| 対応 | Pages関連Actionをv4へ戻す | 互換性が確認できるまで安全側へロールバック |
影響を受ける可能性がある環境
今回のPR自体はAzureのawesome-azdリポジトリに対する個別修正です。そのため、すべてのGitHub Actions利用者に同じ障害が発生するという意味ではありません。
ただし、次の条件に当てはまる環境では、同様の確認を行う価値があります。
| 確認すべき環境 | 理由 |
|---|---|
| GitHub PagesをGitHub Actionsで公開している | upload-pages-artifactとdeploy-pagesを使う可能性が高い |
actions/upload-pages-artifact@v5を使っている | Pages用アーティファクト生成・アップロードに関係する |
actions/deploy-pages@v5を使っている | Pagesへの公開処理に関係する |
| Docusaurus、VitePress、Astro、Next.js静的エクスポートなどをPagesへ公開している | ビルド成果物と公開内容のズレに気づきにくい |
gh-pagesブランチとActionsデプロイを併用している | フォールバックや公開元の混在で原因切り分けが難しくなる |
| 本番デプロイ後の表示確認を自動化していない | ワークフロー成功でも表示崩れを検知できない |
特に注意したいのは、GitHub Pagesの公開元がブランチなのかGitHub Actionsなのかという設定です。GitHub公式ドキュメントでは、カスタムワークフローを使うにはリポジトリ側でGitHub Pagesの設定を有効にする必要があると説明されています。(GitHub Docs)
管理者・開発者がまず確認すべき設定
今回のようなGitHub ActionsとGitHub Pagesの不整合は、単にActionのバージョンだけを見ても判断できません。次の順番で確認すると、原因を切り分けやすくなります。
release.ymlやpages.ymlで使っているActionのバージョンを確認する
まず、GitHub Pagesへデプロイしているワークフローを開きます。一般的には次のようなファイル名です。
.github/workflows/release.yml
.github/workflows/pages.yml
.github/workflows/deploy.yml次のActionを検索してください。
actions/upload-pages-artifact
actions/deploy-pagesv5を使っていて、かつ本番表示に異常がある場合は、v4への一時的な切り戻しを検討します。
- name: Upload Pages artifact
uses: actions/upload-pages-artifact@v4
with:
path: ./build
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4実務では、単に@v4と書くよりも、組織のセキュリティ方針に応じてコミットSHAでピン留めする方法もあります。今回のPRでも、v4へ戻しつつSHAピン留めは維持されています。(GitHub)
GitHub Pagesの公開元を確認する
GitHub Pagesの設定で、公開元が意図したものになっているか確認します。
確認場所は次の通りです。
Repository
→ Settings
→ Pages
→ Build and deployment
→ SourceGitHub Actionsで公開する場合は、SourceがGitHub Actionsになっている必要があります。ブランチ公開とActions公開が混在していると、「ワークフローは成功したが、実際には別のブランチの内容が表示されている」という状態を招きます。
デプロイジョブの権限を確認する
GitHub Pagesのデプロイジョブには、少なくとも次の権限が必要です。
permissions:
contents: read
pages: write
id-token: writeGitHub公式ドキュメントでも、deploy-pagesを正しく動作させるにはpages: writeとid-token: writeが必要とされています。pages: writeはPagesデプロイを作成するため、id-token: writeはOIDCトークンを要求するために使われます。(GitHub Docs)
権限不足の場合は明確なエラーになることもありますが、環境・設定・Actionの組み合わせによっては、別の問題と混ざって見えることがあります。ワークフローを更新したときは、バージョンだけでなくpermissionsも同時に確認しましょう。
needsでビルドとデプロイの順序を明確にする
ビルドジョブとデプロイジョブを分けている場合、deployジョブにはneedsを設定します。
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Build
run: npm run build
- name: Upload artifact
uses: actions/upload-pages-artifact@v4
with:
path: ./build
deploy:
needs: build
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4公式ドキュメントでも、ビルドステップとデプロイをリンクするためにneedsを設定する例が示されています。これがないと、デプロイジョブが期待する成果物を正しく参照できない構成になりやすくなります。(GitHub Docs)
「Actionsは成功しているのにサイトが壊れる」を防ぐ確認方法
今回の修正から得られる最大の教訓は、CI成功と本番表示の正常性を分けて考えることです。
GitHub Actionsの画面で緑のチェックが付いていても、次の状態は起こり得ます。
- 間違ったディレクトリをアップロードしている
- アーティファクトは作成されたが、中身が期待と違う
- デプロイは成功したが、Pagesが別のソースを表示している
- ルーティングやベースURLの設定が本番URLと合っていない
- 静的サイトジェネレーターの出力先と
path指定がずれている
本番デプロイ後は、最低限次の項目を確認します。
| 確認項目 | 見るべきポイント | 例 |
|---|---|---|
| トップページ | 期待したアプリ・ドキュメントが表示されるか | Docusaurusの画面が出るか、READMEだけになっていないか |
| 主要ページ | ルーティングが壊れていないか | /docs/や/getting-started/が404にならないか |
| CSS/JS | アセットが読み込まれるか | DevToolsで404が出ていないか |
| Actionsログ | アップロード対象パスが正しいか | path: ./buildやpath: ./distが実際の出力先と一致するか |
| Pages設定 | Sourceが意図通りか | GitHub Actionsか、ブランチ公開か |
| Environment | github-pages環境にデプロイされているか | 環境保護ルールや承認フローが想定通りか |
手動確認だけに頼ると、夜間や休日のデプロイで見落としやすくなります。重要な公開サイトでは、デプロイ後にHTTPステータスやページ内の特定文字列を確認する軽量なチェックを追加すると安心です。
例として、デプロイ後にトップページへアクセスし、期待する文字列が含まれるか確認するステップを別ワークフローや監視ツールで実行できます。
curl -fsSL https://example.github.io/project/ | grep "期待するサイト名"このような単純なチェックでも、「READMEだけが表示されている」「空のページが返っている」といった事故を早期に検知できます。
v5へ移行済みのチームはすぐv4へ戻すべきか
結論として、すべての環境で機械的にv4へ戻す必要はありません。ただし、GitHub Pagesの本番表示に異常がある、またはPages関連Actionのv5化を直近で行った場合は、切り戻しを有力な選択肢として検討すべきです。
判断基準は次の通りです。
| 状況 | 推奨対応 |
|---|---|
| v5へ更新後、本番サイトが意図しない内容を表示している | v4へ一時ロールバックし、表示を確認する |
| v5へ更新したが、本番表示も正常で監視もある | 直ちに戻す必要はないが、リリースノートとワークフローを記録する |
| これからv5へ上げる予定 | 本番反映前にステージングまたは一時ブランチでPages表示まで検証する |
gh-pagesブランチ公開とActions公開が混在している | まず公開元とワークフロー構成を整理する |
| DependabotなどでActionを自動更新している | Pages関連Actionのメジャー更新は自動マージ対象から外す |
今回のPRでも、actions/deploy-pages側が対応したリリースを出すまでv4へ戻す、という趣旨が示されています。これは実務上も妥当な判断です。メジャーバージョン更新は、セキュリティ面やランタイム更新のメリットがある一方で、デプロイ経路のような本番影響が大きい部分では、検証なしに適用するとリスクが高くなります。(GitHub)
GitHub Pagesデプロイで失敗しやすいポイント
GitHub ActionsからGitHub Pagesへ公開する構成では、失敗の原因が「ビルド」「アーティファクト」「Pages設定」「公開URL」のどこにあるか分かりにくいことがあります。
特に次のポイントは、レビュー時に必ず確認しましょう。
アップロードするディレクトリが正しいか
静的サイトジェネレーターによって出力先は異なります。
| ツール・構成 | よくある出力先 |
|---|---|
| Docusaurus | build/ |
| Vite | dist/ |
| Astro | dist/ |
| Next.js静的エクスポート | out/ |
| Jekyll | _site/ |
upload-pages-artifactのpathが実際の出力先と違うと、ワークフローは成功しても空に近い成果物や意図しないディレクトリを公開してしまうことがあります。
- name: Upload Pages artifact
uses: actions/upload-pages-artifact@v4
with:
path: ./buildメジャーバージョン更新を通常の依存関係更新と同じ扱いにしない
v4からv5のような更新は、単なるパッチ更新ではありません。特にGitHub Pagesのデプロイに関係するActionは、本番公開に直結します。
レビューでは次の観点を入れましょう。
- リリースノートに破壊的変更やランタイム変更がないか
- 関連Actionとの組み合わせに互換性があるか
- ビルドだけでなく、実際のPagesデプロイまで検証したか
- ロールバック手順が明確か
- SHAピン留めしている場合、タグだけでなくSHAも正しく更新されているか
PR #876ではActionsの更新が含まれており、レビューで「v4→v5はメジャーバージョン更新であり、デプロイ経路の確認が必要」と指摘されていました。結果的に、この指摘は非常に重要だったことが分かります。(GitHub)
gh-pagesブランチを別ワークフローで更新していないか
今回のPR説明では、Pagesが期待した成果物ではなく、sync-gh-pages.ymlがgh-pagesへpushするソースツリー側を表示していたとされています。(GitHub)
このように、複数のワークフローがPages公開に関係していると、原因調査が難しくなります。
たとえば、次のような構成は注意が必要です。
release.yml → GitHub Actions経由でPagesへデプロイ
sync-gh-pages.yml → gh-pagesブランチへ強制push
Settings > Pages → gh-pagesブランチを参照この場合、どの経路が最終的な公開内容を決めているのかを明確にする必要があります。理想は、公開方式を1つに統一し、不要な同期ワークフローを停止することです。
実務で使える対応手順
すでにGitHub Pagesの表示に異常が出ている場合は、次の順番で対応すると安全です。
| 手順 | 作業 | 判断ポイント |
| -: | ——————————— | ———————————————— |
| 1 | 現在の公開サイトを確認する | README表示、白画面、404、CSS欠落がないか |
| 2 | 直近のPRでPages関連Actionが更新されていないか確認する | upload-pages-artifact、deploy-pagesのメジャー更新を見る |
| 3 | release.ymlなどのワークフローを確認する | path、permissions、needs、environmentを確認 |
| 4 | 必要に応じてv4へ一時ロールバックする | 変更範囲をPages関連Actionに限定する |
| 5 | 手動でデプロイを再実行する | workflow_dispatchがある場合は活用する |
| 6 | 公開URLで表示確認する | Actions成功ではなく、実画面を確認する |
| 7 | 再発防止を入れる | デプロイ後チェック、PRレビュー基準、Dependabotルールを整備する |
ロールバック時は、他の更新をまとめて戻さないことが重要です。今回のPRのように、原因と疑われるPages関連Actionだけを戻すと、影響範囲を小さく保てます。
再発防止のためにチームで決めておきたいルール
GitHub Actionsの更新は、セキュリティやランタイム対応のために避けて通れません。ただし、デプロイ系Actionの更新は、通常のライブラリ更新よりも慎重に扱うべきです。
チームでは、次のようなルールを決めておくと運用が安定します。
| ルール | 具体例 |
|---|---|
| Pages関連Actionのメジャー更新は自動マージしない | actions/upload-pages-artifact、actions/deploy-pagesはレビュー必須にする |
| PRレビューで本番デプロイ経路を確認する | ビルド・テストだけでなく、Pages公開まで確認する |
| SHAピン留めの方針を決める | タグ運用かSHA固定かを組織で統一する |
| デプロイ後の表示確認を自動化する | curl、Playwright、監視サービスでトップページを検証する |
| ロールバック手順を文書化する | どのActionをどのバージョンへ戻すか記録する |
| Pages公開方式を統一する | GitHub Actions公開とブランチ公開を混在させない |
特に、DependabotやRenovateでGitHub Actionsを自動更新している場合は、actions/*のメジャーバージョン更新を自動マージしない設定にしておくと安全です。小さな更新に見えても、デプロイの最終段に関わるActionは本番影響が大きいためです。
まとめ：GitHub ActionsのPagesデプロイは「成功表示」ではなく「公開結果」まで確認する
今回の「Revert Pages actions v4->v5 in release.yml to fix broken prod deploy」は、GitHub Pages向けActionをv5からv4へ戻し、本番デプロイの不具合を解消するための修正です。
管理者・開発者が取るべき行動は明確です。
まず、actions/upload-pages-artifactとactions/deploy-pagesのバージョンを確認してください。次に、GitHub PagesのSource、permissions、needs、アップロード対象のpathを確認します。直近でv5へ更新してから本番表示が壊れた場合は、v4への一時ロールバックを検討します。
最も重要なのは、GitHub Actionsのジョブ成功だけで判断しないことです。デプロイ後に公開URLへアクセスし、期待したページが表示されているかを確認する運用を入れてください。GitHub Pagesは静的サイト公開の手軽な選択肢ですが、本番サイトとして使うなら、CIの成功表示と実際の公開結果を分けて監視することが安定運用の近道です。
コメント