Q.Studioから移したmicroCMS×Astroのサイトで、記事を更新したら自動でビルドできますか？

Cloudflare Pagesの管理画面のどこを操作すれば、ビルドを起動するためのURLを取得できるでしょうか。まずは「Workers & Pages」から対象のPagesプロジェクトを選択し、「Settings」タブ内の「Builds」画面を開きます。その中にある「Add deploy hook」をクリックして設定を始めましょう。

設定画面では、フックの識別名とビルド対象とするGitブランチを指定します。名前は「microcms」のように、どこから呼ばれるフックかがわかるものにしてください。ブランチには通常の本番ブランチを指定しますが、ステージング環境で事前にレイアウトを確かめたい場合は確認用ブランチを紐付ける使い分けも役立ちます。保存すると固有のURLが表示されるため、コピーして大切に控えておきます。

この仕組みは、指定URLへHTTP POSTリクエストが届いた際に新しいビルドを開始するもので、Deploy Hooksの紹介記事で案内されています。

たとえばmicroCMSで新着記事を1本公開したとき、その更新イベントをCloudflare Pagesへ自動で届ける設定を作ります。作業はmicroCMSの管理画面で行い、更新を検知したいAPIごとに設定します。該当APIの画面から「API設定」を開き、「Webhook」のメニューへ進んでください。追加ボタンを押すと連携先の選択肢が表示されます。

一覧から「Cloudflare Pages」を選び、先ほどCloudflare側で取得したフックURLを入力欄へ貼り付けます。続いて通知タイミングを設定しましょう。「コンテンツの公開時・更新時」「コンテンツの公開終了時」「公開中コンテンツの削除時」などから、必要な操作にチェックを入れて保存します。ブログとお知らせでAPIを分けているなら、両方にURLを登録してください。片方だけだと、もう片方を更新してもビルドは始まりません。

設定後は、テスト記事を公開または更新して動作を確かめます。直後にCloudflare Pagesの管理画面を開き、デプロイ履歴を確認しましょう。Source列にDeploy Hookと記録され、新しいビルドとデプロイが走り出していれば連携は成功ですね。ただし、ここで確かめられるのはビルドが始まったところまでです。ビルドが成功して記事がサイトに出たかは、別に見ておく必要があります。また、Webhookの通知仕様では、ネットワークエラーや4xx・5xxエラーで送信に失敗しても再送は行われません。失敗した通知は再送されないので、届かなかったときはホスティング側で手動でビルドを実行してください。

管理画面で行うすべての操作に対して、毎回ビルドを起動させる必要があるでしょうか。microCMSでは、公開や更新、公開終了、削除、下書き保存など、操作の種類ごとに通知の有無を選べます。

静的サイト運用でビルドを走らせるべき基本の操作は、「公開時・更新時」「公開終了時」「公開中コンテンツの削除時」の3点です。記事を修正して反映したいときはもちろん、掲載終了で記事を取り下げたり、公開中の記事を下書きに戻したりした際も、公開サイトから該当ページを消すために再ビルドが欠かせません。

予約公開を使う人は、もうひとつ設定があります。「公開時・更新時」のなかは、管理画面での操作、API、レビュー、予約で項目が分かれています。管理画面の項目には予約による公開が含まれないため、予約のチェックも入れてください。そうすれば、予約での新規公開や公開済み記事の更新でもビルドが始まります。予約時刻と同時にサイトへ出るわけではなく、ビルドが終わるまで少し遅れますね。

一方で、通常の下書き保存は通知をオフにしておく運用が適しています。Astroなどの静的サイトはビルド時にAPI経由でデータを読み込みますが、microCMSのステータス仕様では公開中の記事を下書き編集していても、通常の取得処理には公開済みの確定データが返されます。下書き内容は専用キーがないと取得できないため、下書きを保存するたびにビルドを走らせても公開画面は変わりません。作業中の細かな保存でビルドを浪費しないよう、下書き通知は外しておきましょう。ただ、draftKeyや下書き取得の権限を使ってプレビュー用のページを作っている場合は、話が変わってきます。

「microCMSで記事を更新したはずなのに、いつまで経ってもサイトに新しい記事が表示されない」と悩む場面もあるかもしれませんね。自動ビルドが動かないときは、microCMSからの通知送信と、Cloudflare Pages側でのビルド実行のどちらで止まっているかを順に切り分けます。まず確かめたいのが、microCMSのWebhook一覧画面にある切り替えスイッチです。手違いでスイッチが無効になっていると通知そのものが飛びません。

次に、操作内容と通知タイミングの設定が合致しているかを見直します。microCMSの通知条件は操作ごとに分かれており、手動更新だけでなく予約公開やレビュー機能など、今回の操作にチェックが入っていないと通知は行われません。

送信側に問題がなければ、Cloudflare Pagesのデプロイ履歴を確認します。履歴のSource列にDeploy Hookの記録がない場合、登録したフックURLの貼り付けミスが疑われますね。逆に、記録があるのにビルドが失敗しているなら、Cloudflare Pagesのデバッグ手順に従い、DeploymentsからView details、Build logを開いてエラーを確認しましょう。ビルドコマンドや出力フォルダの誤り、APIキーなどの環境変数設定が抜けていないかを点検します。

Astroのサイトでは、環境変数が原因になりがちです。Astroの環境変数ガイドのとおり、Viteの仕組みで読み込む環境変数は、ビルドの時点で値に置き換えられます。microCMSのAPIキーやサービスドメインを手元の.envに書いただけでは、Cloudflareでのビルドには渡りません。Cloudflare Pagesのビルド用環境変数にも同じ値を登録してください。