netlify-deploy

Netlify のデプロイ

最新の CLI

netlify deploy              # manual draft deploy (no CI)
netlify deploy --prod       # deploy straight to production
netlify create              # new project from a natural-language prompt
netlify deploy --allow-anonymous   # temp project, claim within 1 hour
npm update -g netlify-cli   # skew protection needs 23.11.0+

デプロイは、バージョン管理されたアトミックなスナップショットです。Netlify は変更されたファイルのみをアップロードし、すべてのファイルが配置されてからライブサイトを切り替えるため、サイトが不整合な状態になることはありません。デプロイは、プレビューまたはプライマリドメインで配信される本番バージョンにできます。

継続的デプロイと手動デプロイ： Git と Netlify CLI を使ったデプロイは継続的デプロイに対応しており、プッシュするとビルドが自動的に開始されます。ドラッグ＆ドロップと API では、単発の手動デプロイが作成されます。手動デプロイ（netlify deploy）ではビルドコマンドは実行されません。例外は、ログイン中のドラッグ＆ドロップのみです（フレームワークは自動検出されます）。

⚠ サイトのリンクまたは作成時に、.netlify を .gitignore に追加してください。 どのリンク方法でも .netlify/state.json が書き込まれるため、コミットしてはいけません。

デプロイを作成する方法

• Git CD — リポジトリを接続すると、Netlify がプッシュのたびにビルドしてデプロイします（OAuth2 または Netlify GitHub App を使用）。これがデフォルトの方法です。本番デプロイは本番ブランチへのプッシュによって実行されます。本番ブランチは多くの場合、リポジトリのデフォルトブランチ（例：main）ですが、「Branches and deploy contexts」で変更できます。
• CLI — netlify create、netlify deploy、netlify deploy --prod。
• ドラッグ＆ドロップ — https://app.netlify.com/drop。ログイン中の場合は、必要に応じてビルドされます。ログインしていない場合は、ファイルがそのまま公開されます。
• API — ファイルダイジェストまたは ZIP を使ってデプロイを作成します（単発の手動デプロイ）。
• Deploy to Netlify ボタン — 公開テンプレートリポジトリからワンクリックでデプロイできます。
• ビルドフック — ビルドを開始する一意の URL です。（ビルドフックからのデプロイは信頼済みとして扱われ、デプロイリクエストポリシーを回避します。）
• AI エージェント — ダッシュボードから Agent Runners（Claude Code、OpenAI Codex、Google Antigravity）を利用できます。ファイルを変更する実行ごとに、agent-<runID>--<site>.netlify.app に Deploy Preview が自動生成されます。プロンプトの横に表示されるインラインプレビューは、その URL で利用できるものと同じ Deploy Preview です。
• Zapier / n8n — 自動化インテグレーションです。

どの方法を選べばよいかわからない場合は、Deploy Navigator が個別におすすめを提示します：https://docs.netlify.com/start/choose-your-path#deploy-navigator（デプロイ作成ページにも「どこから始めればよいかわかりませんか？」として埋め込まれています）。

netlify.toml のデプロイコンテキスト

リポジトリのルートに配置します。ファイル設定は UI 設定を上書きします。定義済みのコンテキストは production、deploy-preview、branch-deploy、preview-server、dev の 5 つです。ブランチ名もカスタムコンテキストとして使用できます。より具体的なコンテキストが、一般的なコンテキストを上書きします。

[context.production]
  command = "make production"
  [context.production.environment]
    ACCESS_TOKEN = "super secret"
  [[context.production.plugins]]        # plugins REQUIRE double brackets
    package = "@netlify/plugin-sitemap"

[context.deploy-preview.environment]
  ACCESS_TOKEN = "not so secret"

[context.branch-deploy]                 # all branch deploys
  command = "make staging"

[context.staging]                       # one branch; overrides branch-deploy
  command = "npm run build:staging-special"

[context.dev.environment]
  NODE_ENV = "development"

[context."features/branch"]             # quote slashed branch names
  command = "gulp"

⚠ netlify.toml に設定した環境変数は、デプロイ環境では利用できません — UI／CLI／API から設定してください。netlify.toml はコミットされるため、機密情報を含めないでください。代わりに UI／CLI／API からコンテキストごとの環境変数を設定してください。

コンテキストの優先順位に関する詳細は references/netlify-toml.md を、コンテキスト戦略については references/deployment-patterns.md を参照してください。

デプロイプレビューとブランチデプロイ

• デプロイプレビューは、PR/MR（GitHub、GitLab、Bitbucket、Azure DevOps、Cursor Origin）とエージェントの実行に対して自動的にビルドされます。ベースブランチは、本番ブランチまたはブランチデプロイが有効なブランチである必要があります。URL：deploy-preview-<num>--<site>.netlify.app。最初のデプロイが保留中の間、URL は Not Found を返します。
• ブランチデプロイには設定が必要です。Project configuration > Developer settings > Continuous deployment > Branches and deploy contexts > Configure に移動します。対象のブランチ（プレフィックスのワイルドカード features/* に対応）または新しいブランチのすべてを有効にします。URL：<branch>--<site>.netlify.app。ブランチが存在する限り、ブランチデプロイは維持されます。ビルド設定／環境変数には、すべてのブランチに [context.branch-deploy]、特定のブランチに [context.<branch>] を使用します。
• ブランチデプロイが有効なブランチにオープン中の PR がある場合、デプロイプレビューとブランチデプロイの両方が作成されます。
• **エントリーパス：**PR/MR の説明に @netlify /some/path を記載し、新しいコミットをプッシュして再生成します。PR で設定した後は、Netlify Drawer で変更できません。
• デプロイをスキップする： [skip ci] または [skip netlify] を PR/MR のタイトルに記載するとデプロイプレビューがスキップされ、コミットメッセージの任意の場所に記載するとブランチ／本番デプロイがスキップされます。次にマーカーなしのコミットを行うと、スキップされた変更もすべてデプロイされます。

ロック、スキップ、手動での本番デプロイ

• ロック（自動公開を無効化）：Deploys リスト > Lock to stop auto publishing を選択します。新しいデプロイもビルドされますが、公開されません。ロックを解除すると再開します。
• **⚠ Git-Cd サイトで手動の netlify deploy --prod を実行する場合：**本番ブランチに次のプッシュを行うと、手動で公開したデプロイが通知なしに置き換えられます。ユーザーに警告し、公開中のデプロイをそのまま維持する必要がある場合はロックしてください。

デプロイの管理

• **検索：**Deploys タブ（Developer または Team Owner）で、デプロイ ID またはブランチ名を検索し、期間、デプロイコンテキスト、ステータスで絞り込みます。
• **キャンセル：**進行中のデプロイの詳細ページで、Cancel deploy > Yes, cancel deploy を選択します。
• **再試行：**ブランチの HEAD からビルドします（任意でキャッシュをクリアできます）。HEAD が元のデプロイ SHA より先に進んでいる場合も、HEAD からビルドされます。
• **ダウンロード：**成功したデプロイの詳細ページで、Deploy file browser から個別のファイルをダウンロードするか、ヘッダーの Download > Download ready からすべてのファイルを ZIP としてダウンロードします。
• **削除：**Developer または Team Owner のみ可能です。サイトのメイン URL に最後に公開されたデプロイや、進行中のデプロイは削除できません。削除は取り消せず、チームのコストを削減することも、ビルド時間を保持することもありません。

Netlify にデプロイボタン

テンプレートのコードは、GitHub.com または GitLab.com 上の公開リポジトリに置く必要があります。

Markdown：

[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/netlify/netlify-statuskit)

URL のバリエーション（ベースリンク https://app.netlify.com/start/deploy）：

# require/pre-fill env vars (hash, client-side only; values may be null)
...?repository=<repo>#SECRET_TOKEN=specialuniquevalue&CUSTOM_LOGO=

# monorepo base dir (whole repo cloned, builds from blog/)
...?repository=<repo>&base=blog

# clone only a subdirectory
...?repository=<repo>&create_from_path=examples/hello

# deploy a specific branch (sets it as production branch)
...?repository=<repo>&branch=beta-feature

# install required SDK extensions before first deploy
...?repository=<repo>&fullConfiguration=true

ファイルベースのテンプレート設定。リポジトリルートの netlify.toml に [template] を記述します：

[template]
  incoming-hooks = ["Contentful"]
  required-extensions = ["supabase"]

[template.environment]
  SECRET_TOKEN = "change me for your secret token"
  CUSTOM_LOGO = "set the url to your custom logo here"

[template] では環境変数の値やベースディレクトリを設定できません。URL パラメーターを使用してください。[template.environment] のプレースホルダー文字列は、UI のラベルとしてのみ使用されます。

**⚠ テンプレート設定（受信フック、テンプレート環境変数）は、リポジトリのルートからのみ読み込まれます。**ボタンで base を指定してサブディレクトリを対象にすると、ビルドではベースディレクトリの netlify.toml が優先されますが、そこにあるテンプレート設定は無視されます。この制限を明示してください。暗示するだけにしないでください。

シークレットスキャンの失敗

⚠ シークレットスキャンによるデプロイの失敗は、シークレットのように見える値がビルド出力に含まれたことを意味します。本物のシークレットであれば、漏えいです。クライアント／公開出力への含有を中止し、シークレットをローテーションしてください。本物の漏えいがある場合に、スキャナーを黙らせるために SECRETS_SCAN_ENABLED=false を設定することは絶対にしないでください。本当にシークレットではない値については、SECRETS_SCAN_OMIT_KEYS／SECRETS_SCAN_OMIT_PATHS の適用範囲を狭く設定してください。

失敗したデプロイの修正 — ロールバックは不要です

失敗したデプロイが公開されることはありません。以前のデプロイが引き続き公開されているため、復元するものはありません。ロールバックや以前のデプロイの復元を求められた場合は、前提を正してください。失敗したデプロイの後は何も変わっていません。また、問題のある 公開済み デプロイの場合は、前に進む形で修正します。コミットをリバートし、CI で再デプロイします。restoreSiteDeploy や publishDeploy は呼び出さず、ダッシュボードからのロールバックを解決策として案内しないでください。

Netlify はデプロイログの上に なぜ失敗したのか？ という AI 診断を表示します。この診断と推奨される解決策では、クレジットは消費されません。エージェントで修正を選択するとエージェントの実行が開始され、チームの残高からクレジットが消費されます。詳しくは https://docs.netlify.com/resources/troubleshooting/fix-a-failed-deploy/ をご覧ください。

デプロイの権限（プライベートリポジトリ）

Netlify がプライベートリポジトリへのプッシュをビルドするのは、認識済みの作成者（オーナー、デベロッパー、Git コントリビューター。Marketplace のボットも対象）による変更のみです。認識されていない作成者によるマージは 承認待ち となり、ビルドを開始するにはチームオーナーがその作成者をチームアカウントに関連付ける必要があります。ビルドフックによるデプロイは対象外です。

制約と注意事項

• ディレクトリごとのファイル数：54,000 個。 公開ディレクトリ内でこの数を超えるディレクトリがあると、デプロイは失敗します。デプロイあたりの合計ファイル数に制限はありません。
• スキュー保護： すべてのプランが対象です。本番コンテキストのみで有効です。ブランチデプロイ、Deploy Preview、パーマリンクでは適用されず、最新のデプロイが配信されます。Netlify CLI 23.11.0 以降が必要です。Astro 5.15.0 以降では Netlify Adapter によりデフォルトで有効になります。Next.js ではオプトインが必要です。本番デプロイ（またはすべてのデプロイ）でパスワード保護を有効にすると、スキュー保護は無効になります。スキュー保護が機能するのは、本番以外のデプロイのみを保護している場合に限られます。Netlify はハードナビゲーション（Sec-Fetch-Mode: navigate、または Sec-Fetch-Site が存在し same-origin ではない場合）でスキュー保護のシグナルを破棄します。フレームワークのメンテナーは netlify/v1/skew-protection.json を使ってサポートを追加します。
• ⚠ 検索インデックス登録 — 最新のブランチデプロイはインデックス登録されます： Netlify は Deploy Preview と古いブランチデプロイには X-Robots-Tag: noindex を追加しますが、各ブランチの最新のブランチデプロイには追加しません。そのため、staging--<site>.netlify.app はクロールされる可能性があります。いずれにせよ、このヘッダーは保証にはなりません。プレビューやブランチデプロイを検索対象外にするには、プロジェクトの表示設定でプロジェクトをプライベートにする（クレジット制プランのみ）か、本番以外のデプロイでパスワード保護を有効にします（この範囲ならスキュー保護も引き続き機能します）。
• プレビュー URL の公開範囲： Deploy Preview／ブランチデプロイの URL は、パスワード保護またはチームログイン保護を追加しない限り、リンクを知っている人なら誰とでも共有できます。
• 新規プロジェクトの公開範囲： 「デフォルトでプライベート」が設定されたクレジット制プランでは、作成方法にかかわらず、新規プロジェクトはプライベートとして開始します。
• 自動削除： デプロイは30日後（有料プランでは90日後）に削除されます。Enterprise では最長365日まで延長できます。公開済みのデプロイ、直近の正常な本番デプロイ、各ブランチの直近の正常なブランチデプロイは削除されません。Project configuration > Developer settings > Automatic Deletion で設定します。

CLI の全コマンドとフラグについては、references/cli-commands.md をご覧ください。

Netlify の運用ルール（デプロイ）

これらは組織内の規約であり、ドキュメント上の事実ではありません。ctx-gen によってレンダリング済みスキルに統合され、生成されることはありません。スキル保守担当者が管理します。

1. エージェントはデプロイをロールバックしません。古いデプロイを復元するために restoreSiteDeploy または publishDeploy を決して呼び出さないでください。修正を前に進め、コミットを リバートして、CI にデプロイさせてください。
2. デプロイに失敗しても公開されません。失敗時にはロールバックするものはありません。
3. 詳細なガイドはこのスキル内にあります：references/netlify-toml.md、 references/cli-commands.md、references/deployment-patterns.md。
4. フロントマターの説明で、ロールバックや復元を機能として決して宣伝しないでください。「ロールバック」、 「デプロイを復元」などの表現も使わないでください。
5. ユーザーからロールバックや以前のデプロイの復元を求められた場合は、その要望に従うのではなく、前提を正してください。デプロイに失敗した後も以前のデプロイは引き続き公開されており、復元するものはありません。問題のあるデプロイが公開済みの場合は、ルール 1 に従って修正を前に進めてください。 回答として restoreSiteDeploy / publishDeploy や、ダッシュボードからのロールバックを案内しないでください。
6. サイトをリンクまたは作成するときは、必ず .netlify を .gitignore に追加してください。サイトをリンクするどの方法でも .netlify/state.json が書き込まれ、コミットしてはならないためです。リンクする際は必ずこのことを伝えてください。
7. シークレットスキャンによるデプロイ失敗の場合、検出された値が実際のシークレットなら情報漏えいです。クライアント向けまたは公開される出力に含めるのをやめてローテーションしてください。実際の漏えいがあるときに、スキャナーを決して無効化しないでください。シークレットではないことが明らかな値については、SECRETS_SCAN_OMIT_KEYS / SECRETS_SCAN_OMIT_PATHS で対象を限定してください。SECRETS_SCAN_ENABLED=false は使わないでください。
8. Git CD が接続されたサイトで手動の netlify deploy --prod を実行する前に、次に本番ブランチへプッシュすると、手動でデプロイした内容が通知なく置き換えられることをユーザーに警告してください。公開済みのデプロイをそのまま維持する必要がある場合は、ロックするよう提案してください。
9. Netlify へのデプロイボタンでは、テンプレート設定（受信フック、テンプレート環境変数）はリポジトリのルートからのみ読み込まれます。ボタンの対象が base 経由でサブディレクトリに設定されている場合は、この制限を明示してください。暗黙のままにしないでください。