astro-github-actions

Astro GitHub Actions

このスキルは、GitHub Actions を使用して Astro サイト向けの包括的な CI/CD パイプラインを構築するのに役立ちます。目的は、手作業を減らしながら、より高品質なサイトを公開できるよう作成者を支援することです。マージ前に型エラーを検出し、リンク切れを知らせ、ビルドを検証し、デプロイを自動化します。

このスキルの対象範囲

健全な Astro プロジェクトには、いくつかの種類のワークフローが必要です。すべてのサイトにすべてが必要なわけではありません。適切な組み合わせは、プロジェクトで TypeScript、カスタムコンポーネント、コンテンツコレクション、テストを使用しているか、またどこにデプロイするかによって異なります。どのワークフローが適切かを判断し、設定してください。

ワークフローは次のカテゴリに分けられます。

1. 型／コンテンツのチェック — astro check（TypeScript とコンテンツコレクションのスキーマ検証）
2. コード品質 — ESLint と Prettier
3. ビルド検証 — astro build がエラーなく実行されること
4. テスト — ユニットテストとコンポーネントテスト向けの Vitest
5. 品質ゲート — Lighthouse CI（パフォーマンス、アクセシビリティ、SEO、ベストプラクティス）
6. リンクチェック — ビルド済みサイトのリンク切れ検出
7. セキュリティ — 依存関係の脆弱性を検出する npm audit
8. デプロイ — GitHub Pages、Cloudflare Pages、Netlify、または Vercel

各ワークフローの詳細な設定については、すぐに使える YAML テンプレートと設定ファイルを含む references/workflows.md をご覧ください。

リクエストへの対応方法

Step 1: プロジェクトを把握する

ワークフローファイルを作成する前に、対象のプロジェクトについて把握してください。

• TypeScript を使用していますか？ tsconfig.json と .ts／.astro ファイルを確認します。ほぼすべての Astro プロジェクトで astro check を実行するべきですが、.astro のフロントマター、コンテンツコレクションのスキーマ、または src/ に TypeScript がある場合に最も効果を発揮します。
• コンテンツコレクションを使用していますか？ src/content/config.ts または src/content.config.ts を確認します。存在する場合、astro check でスキーマを検証できます。特に有用です。
• テストはありますか？ tests/、__tests__/、*.test.ts、または vitest.config.ts を確認します。存在する場合は、Vitest ワークフローを設定してください。ない場合は、テストを追加すると有用であることを伝えますが、無理に追加させないでください。
• パッケージマネージャーは何ですか？ pnpm-lock.yaml、yarn.lock、または package-lock.json を確認します。ワークフローのインストールコマンド（pnpm i --frozen-lockfile、yarn install --frozen-lockfile、または npm ci）をそれに合わせてください。
• どこにデプロイしますか？ wrangler.toml（Cloudflare）、netlify.toml（Netlify）、vercel.json（Vercel）を確認するか、ユーザーに尋ねてください。ほとんどのホスティングサービスには、Actions を使わずに自動デプロイする独自の GitHub アプリがあります。デプロイワークフローは、ユーザーが Actions での処理を実際に希望する場合にのみ設定してください（通常は GitHub Pages またはセルフホストの場合です）。
• ビルドステップはありますか？ Astro には常に astro build がありますが、package.json のスクリプトが標準の astro build であり、カスタムコマンドではないことを確認してください。
• SSR ですか、それとも静的サイトですか？ astro.config.* で output: 'server' またはアダプターのインポートを確認します。SSR プロジェクトはデプロイ方法が異なり（Cloudflare／Netlify／Vercel のアダプターを使用）、GitHub Pages にはデプロイできない場合があります。

Step 2: ワークフローの組み合わせを提案する

確認した内容に基づいて、設定するワークフローを提案してください。ほとんどの Astro サイトに適した基本構成は次のとおりです。

• astro check（ほぼ常に推奨。Astro で最も有用なチェックです）
• ビルド検証（ほぼ常に推奨。astro check では見逃す可能性のあるインテグレーションのリグレッションを検出します）
• ESLint + Prettier（設定ファイルがある場合、またはユーザーが希望する場合）
• Lighthouse CI（公開 URL があるコンテンツサイトに最適です）
• リンクチェッカー（コンテンツの多いサイトに最適です）
• npm audit（手軽に実行でき、ほぼ常に導入する価値があります）

次の項目は条件に応じて設定します。

• Vitest テスト（テストがある場合）
• デプロイワークフロー（ユーザーが Actions によるデプロイを希望する場合のみ。ほとんどの Astro ホスティングサービスは独自の GitHub アプリを使用します）

ステップ 3：ワークフローファイルを作成する

各ワークフローを個別の YAML ファイルとして .github/workflows/ に作成します。1 つの巨大なワークフローではなく個別のファイルを使うと、PR で状況を確認しやすくなります（各チェックの結果が個別に表示されます）。また、個々のチェックを有効化または無効化しやすくなります。

references/workflows.md のテンプレートを出発点として使い、プロジェクトに合わせて調整します。よくある調整には、パッケージマネージャー、Node のバージョン、ビルド成果物のパス、デプロイ先の変更などがあります。

ステップ 4：補助設定ファイルを作成する

設定したワークフローによっては、次のファイルも必要になる場合があります。

• eslint.config.js — eslint-plugin-astro を含む ESLint のフラット設定
• .prettierrc と .prettierignore — prettier-plugin-astro を含む Prettier の設定
• lighthouserc.json — Lighthouse CI のアサーション
• lychee.toml — リンクチェッカーの設定（lychee を使用する場合）
• vitest.config.ts — Vitest の設定

ステップ 5：シークレットについてのリマインダーを設定する

デプロイワークフローを追加する場合、必要なリポジトリシークレットをユーザーに伝えます。

• GitHub Pages — 不要（GITHUB_TOKEN を使用）
• Cloudflare Pages — CLOUDFLARE_API_TOKEN、CLOUDFLARE_ACCOUNT_ID
• Netlify — NETLIFY_AUTH_TOKEN、NETLIFY_SITE_ID
• Vercel — VERCEL_TOKEN、VERCEL_ORG_ID、VERCEL_PROJECT_ID

次の手順を案内します。Repository Settings > Secrets and variables > Actions > New repository secret。

Cloudflare、Netlify、Vercel の場合は、各プラットフォームがビルド、デプロイ、PR プレビューを自動で処理する独自の GitHub アプリを提供していることも伝えます。Actions を使ったデプロイが有効なのは通常、テスト結果をデプロイの条件にする必要がある場合、プラットフォームにないシークレットを使ってビルドする場合、またはリポジトリのルート以外のパスからデプロイする場合に限られます。

命名規則

各ファイルの役割がすぐに分かる、内容を具体的に示すワークフローファイル名を使います。

• astro-check.yml — astro check（型とコンテンツスキーマ）
• lint.yml — ESLint
• format.yml — Prettier チェック
• build.yml — ビルド検証
• test.yml — Vitest
• lighthouse.yml — Lighthouse CI
• links.yml — リンク切れチェッカー
• security.yml — npm audit
• deploy.yml — ホストにデプロイ

重要な詳細

Node.js のバージョン：Astro には Node 18.20.8 以降、20.3.0 以降、または 22.0.0 以降が必要です。デフォルトでは Node 22 を使用してください。Astro の安定版の対象バージョンに合致し、多くのアダプターが Node 22 を基準にテストされているためです。actions/checkout@v5 と actions/setup-node@v5 を使用してください。

パッケージマネージャーの判定：必ずロックファイルに合わせてください。pnpm-lock.yaml → pnpm/action-setup@v4 と pnpm install --frozen-lockfile を使用します。yarn.lock → yarn install --frozen-lockfile を使用します。package-lock.json → npm ci を使用します。CI では npm install を使用しないでください（再現性がなく、時間もかかります）。

ブランチ名：多くの Astro リポジトリではデフォルトブランチに main を使用していますが、トリガーを記述する前に実際のリポジトリを確認してください。

Astro アダプターと SSR：プロジェクトで @astrojs/cloudflare、@astrojs/netlify、または @astrojs/vercel を使用している場合、ビルド出力は静的な dist/ ディレクトリではない可能性があります。Cloudflare アダプターは dist/ と _worker.js を出力します。Vercel は .vercel/output/、Netlify は .netlify/ を出力します。それに合わせてデプロイ成果物のパスを調整してください。

astro check には @astrojs/check と typescript が必要です：どちらもインストールされている必要があります。devDependencies にない場合、ワークフローは失敗します。すでに package.json にある場合に限り、npm ci の一部として追加してください。それ以外の場合は、ワークフローで明示的にインストールする必要があります。

PR での Lighthouse CI：すべての PR で Lighthouse を実行すると、パフォーマンスの低下を早期に検出できます。標準的なアクションは treosh/lighthouse-ci-action です（Cloudflare Pages、Netlify、Vercel などの）一般公開されているプレビュー URL がある場合は、Lighthouse の対象にデプロイプレビュー URL を指定してください。より現実的な数値が得られます。内部専用の構成では、ランナー内でビルドしてローカルでサーバーを起動してください。

ソースではなく、ビルド済み出力を対象にリンクをチェック：リンクチェッカーは、ビルド済みの dist/ ディレクトリ（またはデプロイ済みのプレビュー URL）を対象に実行してください。Markdown ソースを対象に実行すると、生成されたルートやサイトマップのリンクを見落とします。

Actions によるデプロイより、プラットフォームの GitHub アプリを優先：Cloudflare Pages、Netlify、Vercel にはそれぞれ公式の GitHub アプリがあり、PR プレビュー、ブランチへのデプロイ、ロールバックを、独自に作成した Action より適切に処理できます。まず GitHub アプリを推奨し、ユーザーにその方法を選ぶ具体的な理由がある場合に限り、Actions によるデプロイを提案してください。