netlify-deploy

Netlify デプロイスキル

インテリジェントなプロジェクト構成とデプロイコンテキストの検出機能を備え、Netlify CLI を使って Web プロジェクトを Netlify にデプロイします。

概要

このスキルは次の手順で Netlify へのデプロイを自動化します:

• Netlify CLI の認証を検証
• プロジェクトの構成とフレームワークを検出
• 既存のサイトにリンクするか、新しいサイトを作成
• 本番環境またはプレビュー環境にデプロイ

前提条件

• Netlify CLI: npx 経由でインストール（グローバルインストールは不要）
• 認証: 有効なログインセッションを持つ Netlify アカウント
• プロジェクト: 現在のディレクトリにある有効な Web プロジェクト
• サンドボックスによってデプロイのネットワーク呼び出しがブロックされた場合は、sandbox_permissions=require_escalated を指定して再実行してください。
• デプロイには数分かかる場合があります。適切なタイムアウト値を設定してください。

認証パターン

このスキルは 事前認証済みの Netlify CLI の方式を採用しています:

1. npx netlify status で認証状態を確認
2. 認証されていない場合は、npx netlify login の手順をユーザーに案内
3. 認証を確立できない場合は、エラーを適切に処理して終了

認証には次のいずれかを使用します:

• ブラウザベースの OAuth（主な方法）: netlify login がブラウザを開いて認証を行います
• API キー（代替方法）: NETLIFY_AUTH_TOKEN 環境変数を設定します

ワークフロー

1. Netlify CLI の認証を検証

ユーザーが Netlify にログインしているかを確認します:

npx netlify status

想定される出力パターン:

• ✅ 認証済み: ログイン中のユーザーのメールアドレスとサイトのリンク状態が表示される
• ❌ 未認証: 「Not logged into any site」または認証エラーが表示される

未認証の場合は、ユーザーに次の操作を案内します:

npx netlify login

これによりブラウザウィンドウが開き、OAuth 認証が行われます。ユーザーがログインを完了するまで待ち、その後 netlify status で再度確認してください。

代替方法: API キー認証

ブラウザ認証が利用できない場合、次のように設定できます:

export NETLIFY_AUTH_TOKEN=your_token_here

トークンは次の URL で生成できます: https://app.netlify.com/user/applications#personal-access-tokens

2. サイトのリンク状態を検出

netlify status の出力から次を判断します:

• リンク済み: サイトはすでに Netlify に接続されている（サイト名または URL が表示される）
• 未リンク: サイトをリンクするか、新しく作成する必要がある

3. 既存のサイトにリンクするか、新規作成

リンク済みの場合 → 手順 4 にスキップ

未リンクの場合は、Git リモートを使ってリンクを試みます:

# Check if project is Git-based
git remote show origin

# If Git-based, extract remote URL
# Format: https://github.com/username/repo or [email protected]:username/repo.git

# Try to link by Git remote
npx netlify link --git-remote-url <REMOTE_URL>

リンクに失敗した場合（Netlify 上にサイトが存在しない）:

# Create new site interactively
npx netlify init

これにより、次の内容をユーザーに案内します:

1. チームまたはアカウントの選択
2. サイト名の設定
3. ビルド設定の構成
4. 必要に応じて netlify.toml の作成

4. 依存関係を検証

デプロイの前に、プロジェクトの依存関係がインストールされていることを確認します:

# For npm projects
npm install

# For other package managers, detect and use appropriate command
# yarn install, pnpm install, etc.

5. Netlify にデプロイ

状況に応じてデプロイの種類を選択します:

プレビュー／ドラフトデプロイ（既存のサイトのデフォルト）:

npx netlify deploy

テスト用の固有 URL を持つデプロイプレビューが作成されます。

本番デプロイ（新規サイトや明示的に本番へデプロイする場合）:

npx netlify deploy --prod

ライブの本番 URL にデプロイされます。

デプロイの流れ:

1. CLI がビルド設定を検出する（netlify.toml から読み取るか、ユーザーに確認する）
2. ローカルでプロジェクトをビルドする
3. ビルド済みのアセットを Netlify にアップロードする
4. デプロイ URL を返す

6. 結果を報告

デプロイ後、ユーザーに次の内容を報告します:

• デプロイ URL: このデプロイ固有の URL
• サイト URL: 本番 URL（本番デプロイの場合）
• デプロイログ: ログを確認できる Netlify ダッシュボードへのリンク
• 次のステップ: サイトやダッシュボードを表示するための netlify open の利用を提案

netlify.toml の扱い

netlify.toml ファイルが存在する場合、CLI は自動的にそれを使用します。存在しない場合、CLI は次の項目を尋ねます:

• ビルドコマンド: 例 npm run build、next build
• 公開ディレクトリ: 例 dist、build、.next

一般的なフレームワークのデフォルト:

• Next.js: ビルドコマンド npm run build、公開ディレクトリ .next
• React (Vite): ビルドコマンド npm run build、公開ディレクトリ dist
• 静的 HTML: ビルドコマンドなし、公開ディレクトリは現在のディレクトリ

可能であれば package.json からフレームワークを検出し、適切な設定を提案してください。

完全なワークフローの例

# 1. Check authentication
npx netlify status

# If not authenticated:
npx netlify login

# 2. Link site (if needed)
# Try Git-based linking first
git remote show origin
npx netlify link --git-remote-url https://github.com/user/repo

# If no site exists, create new one:
npx netlify init

# 3. Install dependencies
npm install

# 4. Deploy (preview for testing)
npx netlify deploy

# 5. Deploy to production (when ready)
npx netlify deploy --prod

エラー処理

一般的な問題と解決策:

"Not logged in" → npx netlify login を実行します

"No site linked" → npx netlify link または npx netlify init を実行します

"Build failed" → netlify.toml の build command と publish directory、または CLI のプロンプトで指定した値を確認します → 依存関係がインストールされていることを確認します → 具体的なエラーについてビルドログを確認します

"Publish directory not found" → build command が正常に実行されたことを確認します → publish directory のパスが正しいことを確認します

トラブルシューティング

エスカレーションされたネットワークアクセス

ネットワークの問題（タイムアウト、DNS エラー、接続リセットなど）によりデプロイに失敗した場合は、エスカレーションされた権限（sandbox_permissions=require_escalated を使用）でデプロイを再実行してください。サンドボックスのネットワーク設定により送信リクエストがブロックされている場合、デプロイにはエスカレーションされたネットワークアクセスが必要です。

ユーザーへの案内例:

The deploy needs escalated network access to deploy to Netlify. I can rerun the command with escalated permissions—want me to proceed?

環境変数

シークレットと設定について:

1. シークレットを Git にコミットしないでください
2. Netlify ダッシュボードで設定します: Site Settings → Environment Variables
3. ビルド内では process.env.VARIABLE_NAME でアクセスします

ヒント

• 本番環境に反映する前にテストするには、まず netlify deploy（--prod なし）を使用します
• netlify open を実行すると、Netlify ダッシュボードでサイトを表示できます
• netlify logs を実行すると、関数のログを表示できます（Netlify Functions を使用している場合）
• Netlify Functions を使ったローカル開発には netlify dev を使用します

リファレンス

• Netlify CLI ドキュメント: https://docs.netlify.com/cli/get-started/
• netlify.toml リファレンス: https://docs.netlify.com/configure-builds/file-based-configuration/

同梱リファレンス（必要に応じて読み込み）

• CLI コマンド
• デプロイパターン
• netlify.toml ガイド