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

出力の想定パターン：

• ✅ 認証済み：ログイン中のユーザーのメールアドレスとサイトのリンク状態が表示されます
• ❌ 未認証：「どのサイトにもログインしていません」または認証エラーが表示されます

未認証の場合は、ユーザーを案内します。

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
• Static 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 ガイド