AstroをCloudflare Pagesへ出す前のRelease Gate設計

結論

AstroをCloudflare Pagesへ安全に出すRelease Gateは、npm ci → npm run check → npm run build → 必須生成物確認 → 差分・承認 → deploy → 公開URL確認の順に分けます。本番資格情報は、検証を通過したdeploy jobだけへ渡します。

筆者が2026年8月13日に確認したcodeagent.jpの非公開リポジトリでは、現行workflowはmainへのpushまたは手動実行で npm ci、npm run build、Cloudflare Pages Direct Uploadを行います。一方、npm run check と公開後HTTP確認は含まれていません。このスナップショットは読者が公開URLから検証できないため、サイト固有の事例として明記し、一般的な推奨はAstro、Cloudflare、GitHubの公開公式Docsで裏付けます。既存workflowを変更した、または本番へ公開したという報告ではありません。

この記事の対象読者

Astroの静的サイトをCloudflare PagesへGitHub Actionsで公開している人
build成功だけでは不安で、型・コンテンツ・生成物まで検査したい人
main pushの自動公開を維持しながら、公開前に確実な停止点を作りたい人
複数サイトへ共通のRelease Gateを再利用したいチーム

記事制作からSEO確認までの全体像は、Codexで個人開発サイトのSEO改善と記事公開を回す実例も参考になります。

Gate 1

再現

npm ciでlockfileどおりに依存関係を入れる。
Gate 2

静的検査

npm run checkで型とコンテンツの診断を通す。
Gate 3

生成

npm run buildと必須ファイル確認を通す。
Gate 4

承認

差分、公開日、draft、出典、未関係変更を確認する。
Gate 5

公開

資格情報を持つjobだけがPagesへ送る。
Gate 6

検証

公開URL、canonical、sitemap、導線を確認する。

失敗した段階で止め、後続へ本番資格情報を渡さない。

現行workflowの事実を棚卸しする

対象は、筆者がアクセスできる非公開リポジトリ内の .github/workflows/deploy-cloudflare-pages.yml と package.json です。2026年8月13日時点の状態は次の通りです。以下は匿名化した構成の要約であり、外部から検証できる公開一次資料ではありません。

項目	現行状態	Release Gate上の評価
トリガー	`main` push、`workflow_dispatch`	自動公開として明確
同時実行	固定group、`cancel-in-progress: true`	古い実行の競合を抑える
権限	`contents: read`、`deployments: write`	必要範囲を明示
Node	`.nvmrc`を`setup-node@v6`で利用	ローカルとCIを揃えやすい
依存導入	`npm ci`	lockfile再現性あり
静的検査	`npm run check`なし	PR側の必須ゲートが必要
ビルド	`npm run build`	Astro buildとPagefind生成を実行
デプロイ	Wrangler Action v3、Wrangler 4、`dist`	Pages Direct Uploadに一致
本番資格情報	GitHub Secretsからdeploy stepへ渡す	deploy jobへ限定したい
公開後確認	deployment URLを表示	HTTP・内容確認を追加したい

ここで大事なのは、「現行workflowに不足がある」ことと「今すぐ同じファイルへすべて詰め込む」ことは別だという点です。main pushで即デプロイされる構成では、公開前の停止点をPRに置く方が明確です。

なぜcheckとbuildを分けるのか

Astro CLI公式Docsによると、astro check は .astro ファイルなどの診断・型検査を行い、エラーがあれば終了コード1で終わるCI向けコマンドです。astro build はデプロイ用のサイトを生成し、静的サイトでは既定で dist/ へ出力します。

役割を一つにまとめず、失敗理由を分けます。

コマンド	確認するもの	失敗時の扱い
`npm ci`	lockfileと依存関係の再現	環境またはlockfileを直す
`npm run check`	Astro診断、型、コンテンツschema	コード・frontmatterを直す
`npm run build`	全ルート生成、MDX評価、Pagefind	ビルド・リンク・生成処理を直す
生成物assert	`dist`内の必須ファイル	出力設定・slug・draftを直す
公開後smoke	配信されたHTTPとメタ情報	デプロイ停止・切り戻しを判断

npm run buildが成功しても、checkを実行した事実にはなりません。反対に、check成功だけでも全ルートの生成と検索インデックス作成は保証できません。

再利用可能なRelease Gateの設計

検証だけを再利用workflowへ分離すると、本番secretを使わずに複数サイトから呼べます。以下は設計例であり、このリポジトリへ追加済みのworkflowではありません。

name: Reusable Astro Release Gate

on:
  workflow_call:
    inputs:
      required_artifact:
        description: Build後に存在必須とするファイル
        required: false
        type: string
        default: dist/index.html

permissions:
  contents: read

jobs:
  validate:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version-file: .nvmrc
          cache: npm
      - run: npm ci
      - run: npm run check
      - run: npm run build
      - name: Assert required artifact
        shell: bash
        env:
          REQUIRED_ARTIFACT: ${{ inputs.required_artifact }}
        run: |
          artifact="$(realpath -m -- "$REQUIRED_ARTIFACT")"
          dist_root="$(realpath -- dist)"
          case "$artifact" in
            "$dist_root"/*) ;;
            *) echo "required_artifact must stay under dist/" >&2; exit 1 ;;
          esac
          test -f "$artifact"

このゲートにはCloudflareのトークンもアカウントIDも渡しません。呼び出し元はPRでゲートを実行し、main側のdeploy jobはゲート済みコミットだけを扱います。サイト固有の必須生成物はinputで切り替えます。workflow inputはシェルへ直接展開せず環境変数に渡し、realpathでdist/の外へ出ないことも確認します。

再利用性を高める境界は次の通りです。

共通化する: Node設定、npm ci、check、build、タイムアウト、成果物assert
サイト側に残す: 必須URL、canonical、sitemap名、環境変数、承認者
deploy側にだけ置く: Cloudflare API token、account ID、project name
公開後に置く: 配信URL、コンテンツ本文、キャッシュ、主要リンクのsmoke test

Cloudflare PagesのDirect Upload CIガイドも、GitHub Actionsでビルド・テストとWranglerデプロイを自動化できること、資格情報をGitHub Secretsへ置くことを示しています。

PRから公開までの具体手順

1. ローカル差分を限定する

記事公開なら対象MDX、必要な画像、意図した内部リンクだけが差分に入っているか確認します。未追跡・未コミットの別作業をビルドや公開へ混ぜません。

git status --short
npm ci
npm run check
npm run build
Test-Path -LiteralPath dist/index.html
Test-Path -LiteralPath dist/sitemap-index.xml

npm ci は環境を更新するため、作業中の依存関係を保ちたい場合はクリーンな作業コピーやCIで実行します。生成物名は各サイトの設定に合わせてください。

2. 記事固有の生成物を確認する

公開slugが example-post なら、dist/posts/example-post/index.html の存在を確認します。本文タイトル、draft: false、公開日、canonical、構造化データ、内部リンクも生成HTMLから検証します。MDXの公開要件は記事のschemaに合わせます。

3. PRで再利用ゲートを必須にする

pull_requestで共通workflowを呼び、成功をbranch protectionまたはrulesetのrequired checkにします。Claude CodeのCI自動化例のようなAIエージェントを使う場合も、エージェントの完了報告ではなくCIの終了コードを判定根拠にします。

4. 承認時に公開条件を読む

レビューでは文章だけでなく、次を確認します。

公開対象ファイルと意図しない差分
draft、pubDate、sourceCheckedAt
一次情報のURLと確認日
内部リンクの実在
著作権・機密・個人情報
検証ログと既知の未確認事項

5. main側でdeployする

現行codeagent.jp workflowは、main push後に dist を pages deploy します。再利用ゲートを導入する場合は、PRで同一コミットを検証済みにするか、deploy workflow内のdeploy jobをvalidate jobへ依存させます。どちらの場合も、検証失敗時にはCloudflare secretへ到達させません。

6. 公開URLを確認する

workflowが表示するdeployment URLだけでなく、正規URLも確認します。

curl --fail --silent --show-error --location \
  --output /tmp/article.html \
  https://example.com/posts/example-post/

grep -F '<link rel="canonical" href="https://example.com/posts/example-post/">' \
  /tmp/article.html

実運用では、タイトル、canonical、sitemap収録、主要内部リンク、404ページ、必要な静的アセットまで確認します。プレビューURLと正規URLではキャッシュやドメイン設定が異なるため、両者を混同しません。

判断表：どこで止めるか

事象	自動判定	人間判断	対応
`npm ci`失敗	可能	原因確認	deployしない
`npm run check`失敗	可能	修正範囲確認	deployしない
`npm run build`失敗	可能	原因確認	deployしない
必須HTML・sitemap欠落	可能	出力要件確認	deployしない
未関係差分の混入	一部可能	必須	PRを戻す
出典未確認・日付不整合	一部可能	必須	公開を延期
secretらしき値を検知	可能	必須	停止・失効・調査
デプロイ後に非2xx	可能	影響判断	再試行または切り戻し
canonical・本文が不一致	可能	影響判断	公開完了にしない

GitHub ActionsのSecrets解説は、資格情報の権限を最小化すること、ログの自動マスキングが常に保証されるわけではないことを説明しています。secretを検証jobへ渡さず、deploy stepでも値をechoしない設計が基本です。

公開前チェックリスト

公開後チェックリスト

workflowが対象コミットで成功した
deployment URLと正規URLが2xxを返した
title、description、canonicalが正しい
sitemapに公開URLが含まれる
主要な内部リンクと静的アセットが取得できる
404、JavaScriptエラー、レイアウト崩れがない
問題発生時の停止・切り戻し記録を残した

Cloud型コーディングエージェントを公開フローへ組み込む場合は、GitHub Copilot coding agentのPR運用も参考になります。誰が変更したかにかかわらず、同じゲートを通すことが重要です。

よくある質問

npm run buildが成功すればnpm run checkは不要ですか？

不要とはいえません。Astro公式Docsではastro checkは診断や型検査を行い、エラー時に終了コード1を返すCI向けコマンドです。buildと検出範囲が同じではないため、公開ゲートではcheckとbuildを別々に通します。

mainへのpushで自動デプロイする場合、どこで公開を止めますか？

mainへ入った時点でデプロイが始まるなら、停止点はmainの手前です。pull_requestでRelease Gateを必須チェックにし、ブランチ保護またはrulesetで成功したPRだけをmainへ入れる設計にします。

Cloudflare PagesのデプロイURLが出れば公開確認は完了ですか？

完了ではありません。URLの2xx応答、記事タイトル、canonical、sitemap、主要リンクを確認し、期待したコミットが配信されていることまで記録します。認証やキャッシュの影響があるサイトでは追加の確認も必要です。

まとめ

AstroのRelease Gateは、一つの巨大なdeploy workflowではなく、再現、静的検査、生成、承認、公開、公開後確認という停止可能な段階で作ります。astro check と astro build は役割が違うため両方を実行し、サイト固有の必須生成物も確認します。

codeagent.jpの現行workflowには、npm ci、build、Direct Upload、同時実行制御、最小限の権限があります。一方、2026年8月13日時点では npm run check と公開後smoke testはありません。まずPRの再利用ゲートをmainの必須条件にし、通過したコミットだけへ本番資格情報を渡す設計にすると、既存の自動公開を保ちながら明確な停止点を持てます。

検証メモと一次情報

サイト固有の現行workflowとpackage.json: 筆者が2026年8月13日に非公開リポジトリのローカルスナップショットで確認（公開URLなし）
Astro Docs: CLI Commands
Astro Docs: Deploy your Astro Site to Cloudflare
Cloudflare Pages: Use Direct Upload with continuous integration
GitHub Docs: Workflow syntax for GitHub Actions
GitHub Docs: Secrets