netlify-deploy

---
name: netlify-deploy
description: Create and manage Netlify deploys — Git continuous deployment, CLI manual/anonymous deploys, Deploy to Netlify buttons, drag-and-drop, and per-context netlify.toml build settings. Use when linking a repo, deploying from the CLI, setting up Deploy Previews or branch deploys, configuring deploy contexts, adding skew protection, fixing a failed or secrets-flagged deploy, or wiring build hooks and Deploy to Netlify buttons.
license: MIT
---

# Netlify deploy

## Deploy context config (netlify.toml, current form)

Configure per-context build settings in `netlify.toml` at the repo root. Five predefined contexts: `production`, `deploy-preview`, `branch-deploy`, `preview-server`, `dev`. Branch names also work as custom contexts (a `staging` branch matches a `staging` context).

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

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

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

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

# Specific-branch context (overrides branch-deploy):
[context.feature]
  command = "make feature"

[context."features/branch"]
  command = "gulp"
```

Precedence: site globals < context overrides; production overrides globals when building production; more specific contexts (a named branch) override general ones (`branch-deploy`). Only explicitly-set options are overridden. File-based config overrides UI settings.

**Footgun — secrets in netlify.toml:** `netlify.toml` is committed to your repo. Do not put sensitive env values here, especially for public repos. Set secrets via the Netlify UI/CLI/API instead. Also: env vars declared in `netlify.toml` are NOT available to the deploy environment (Functions/Runtime/Post-processing scopes) — only UI/CLI/API-created vars are.

## CLI deploys

```bash
netlify create              # new project from a natural-language prompt
netlify deploy              # manual deploy, no continuous deployment
netlify deploy --prod       # deploy directly to production
netlify deploy --allow-anonymous   # temp deploy, claim within 1 hour
npm update -g netlify-cli   # skew protection needs CLI v23.11.0+
```

Manual deploys do NOT run a build command (exception: Netlify Drop builds for you when logged in). Anonymous deploys create a temporary project claimable within one hour; on claim it adopts the team's default visibility.

**Footgun — link writes `.netlify/state.json`:** every linking/create path writes `.netlify/state.json`. Add `.netlify` to `.gitignore` so it is never committed.

**Footgun — manual `--prod` on a Git-connected site:** the next push to the production branch silently replaces your hand-shipped deploy. Warn the user before running it; if the deploy must stay live, lock the published deploy.

## Git continuous deployment

Connect a Git repo (Git provider OAuth2 or the Netlify GitHub App). Netlify runs your build command and deploys on every push. Production deploys are triggered by pushes to the production branch (default `main`); Deploy Previews are built for pull/merge requests and agent runs.

## Deploy Previews & branch deploys

- Deploy Previews build by default for PRs/MRs and agent runs. Base branch of a Deploy Preview must be a production branch or a branch with branch deploys enabled.
- Branch deploys are OFF by default — a Developer/Owner must enable them: Project configuration > Build & deploy > Continuous Deployment > Branches and deploy contexts > Configure. Add individual branches, use a `features/*` prefix wildcard, or select **All**.
- URL prefixes: branch deploys `<branch>--`; PR/MR previews `deploy-preview-<number>--`; agent previews `agent-<runID>--`; permalinks `<deployID>--`.
- While the initial Deploy Preview builds, its URL returns `Not Found`.

**Deploy Preview entry path** — set in the PR/MR description (updates the PR comment link):
```markdown
@netlify /start/choose-your-path
```
Push a new (or empty) commit to regenerate the link. Once set in the PR/MR, you cannot override the entry path in the Netlify Drawer.

## Skip a deploy

Add `[skip ci]` or `[skip netlify]` to a PR/MR title (skips the Deploy Preview) or anywhere in a commit message (skips branch/production deploy). For a multi-commit push, put it in the most recent commit. The next commit without the token deploys all skipped changes.

## Deploy to Netlify button

Template code must be in a **public** GitHub.com or GitLab.com repo.

```md title="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 parameters (query params; env vars go in the URL hash):
```txt
# require/set env vars via hash (values may be null; processed client-side, not logged)
...?repository=REPO#SECRET_TOKEN=value&CUSTOM_LOGO=
&fullConfiguration=true   # extra step to install SDK extensions + configure before deploy
&base=blog                # alternate base dir for monorepos (repo still fully cloned)
&create_from_path=examples/hello   # clone only this subdirectory
&branch=beta-feature      # set production branch to this branch
```

File-based template config in root `netlify.toml` `[template]` section:
```toml
[template]
  incoming-hooks = ["Contentful"]
  required-extensions = ["supabase"]
[template.environment]
  SECRET_TOKEN = "change me for your secret token"   # label only; cannot set real values
```
`[template]` cannot set env var values (use the URL hash) or a base directory (use `base`). With an alternate `base`, the `netlify.toml` in the base directory wins over root config for that site's builds. `USAGE.md` at repo root shows extra instructions during the `fullConfiguration` flow.

## Drag and drop (Netlify Drop)

Drag a folder to https://app.netlify.com/drop. Logged in: Netlify detects the framework and builds before publishing (a pre-built output folder also works). Not logged in: files publish as-is. Update a drag-and-drop site by dropping the new output folder at the dropzone on the site's **Deploys** page (works for any non-Git site).

## Build hooks

Build hooks give unique URLs to trigger builds/deploys. Builds from build hooks are treated as trusted and are NOT subject to the Deploy Request Policy.

## Managing deploys

- **Find:** Deploys tab; search by deploy ID or branch; filter by time frame, deploy context, and status.
- **Lock (pause publishing):** on the Deploys list, **Lock to stop auto publishing**. New deploys still build but don't publish. **Unlock to start auto publishing** to resume. Use this to keep a specific deploy live.
- **Cancel:** on the in-progress deploy's detail page, **Cancel deploy**.
- **Retry:** builds from the branch HEAD — if HEAD moved past the original deploy SHA, it still builds from HEAD.
- **Download:** deploy detail page — single file via **Deploy file browser**, or all files as ZIP via header **Download**.
- **Delete:** Developer/Team Owner only. You cannot delete the currently-published deploy or one in progress. Permanent; does not reduce cost or preserve build minutes.

Netlify auto-deletes deploys older than 30 days (90 days on paid plans); failed/canceled deploys are cleaned up on the same schedule. It never auto-deletes the published deploy, the most recent successful production deploy, or the most recent successful branch deploy per branch.

**Fix a failed deploy:** a failed deploy never publishes — the previously published deploy stays live, so there is nothing to restore. Fix forward: use the **"Why did it fail?"** diagnosis above the deploy log, revert the offending commit, and let CI redeploy. Retry (optionally clearing cache) rebuilds from branch HEAD.

## Skew protection

Available on all plans. Routes requests to the server version that matches each client, avoiding version skew across deploys. Requires Netlify CLI v23.11.0+ for CLI deploys.

- **Production context only.** Branch deploys, Deploy Previews, and permalinks bypass skew protection and serve the latest deploy for that context.
- Framework support: Astro 5.15.0+ (on by default via the Netlify adapter); Next.js (optional; older versions need a config change). Framework maintainers add support via `netlify/v1/skew-protection.json`.
- **Password protection:** works only if you protect non-production deploys only. Protecting production deploys (or all deploys) disables/ignores skew protection.
- Netlify discards skew signals on hard navigation (`Sec-Fetch-Mode: navigate`, or `Sec-Fetch-Site` present and not `same-origin`).

## Secrets scanning failures

If a deploy fails secrets scanning and the flagged value is a real secret, that is a leak: stop shipping it in client/published output and rotate it. Never disable the scanner over a real leak. For genuine non-secrets, scope narrowly with `SECRETS_SCAN_OMIT_KEYS` / `SECRETS_SCAN_OMIT_PATHS` — never `SECRETS_SCAN_ENABLED=false`.

## Constraints

- **54,000 files per directory** max — any directory in your publish dir over this limit fails the deploy. No limit on total files.
- Deploys are atomic: only changed files upload; nothing goes live until the whole deploy is ready.
- Only the published production deploy and most recent branch deploys are indexable; other previews get `X-Robots-Tag: noindex`.
- Deploy Request Policy: private-repo deploys build only for recognized authors (Owners, Developers, Git Contributors; Marketplace bots count). Non-team-member deploys land as **Pending approval** until a Team Owner approves/matches them. Build-hook builds are exempt.
- Retention limit is adjustable only on Enterprise (up to 365 days). Lock/unlock event notifications: Pro and Enterprise.

## More

Deep guides in this skill: `references/netlify-toml.md`, `references/cli-commands.md`, `references/deployment-patterns.md`.

<!-- Gap: deploy-overview states failed/canceled deploys are deleted at 6 months, contradicting the 30/90-day cleanup figure used above; the 30/90-day value is stated here as the documented default. -->

<!-- system: agent-context/deploy/system.md — human-owned, merged by ctx-gen; edit system.md, not this section -->
# Netlify house rules (deploy)

These are org conventions, not docs facts — merged into the rendered skill by
ctx-gen and never generated. Owned by the skills maintainer.

1. Agents do not roll back deploys: never call `restoreSiteDeploy` or
   `publishDeploy` to restore an older deploy. Fix forward — revert the
   commit and let CI deploy it.
2. A failed deploy never publishes; on failure there is nothing to roll
   back.
3. Deep guides live in this skill: `references/netlify-toml.md`,
   `references/cli-commands.md`, `references/deployment-patterns.md`.
4. The frontmatter description must never advertise rollback or restore as a
   capability — no "roll back", "restore a deploy", or equivalent.
5. When the user asks to roll back or restore a previous deploy, correct the
   premise rather than complying: after a failed deploy the previous deploy
   is still live and there is nothing to restore; for a bad published deploy,
   fix forward per rule 1. Do not hand over `restoreSiteDeploy` /
   `publishDeploy` or a dashboard rollback as the answer.
6. Always add `.netlify` to `.gitignore` when linking or creating a site —
   every linking path writes `.netlify/state.json`, which must not be
   committed. Mention it whenever you link.
7. Secrets-scanning deploy failures: if the flagged value is a real secret,
   that is a leak — stop shipping it in client/published output and rotate
   it; never silence the scanner over a real leak. For genuinely non-secret
   values, scope narrowly with `SECRETS_SCAN_OMIT_KEYS` /
   `SECRETS_SCAN_OMIT_PATHS`, never `SECRETS_SCAN_ENABLED=false`.
8. Before running a manual `netlify deploy --prod` on a site with Git CD
   connected, warn the user that the next push to the production branch
   silently replaces the hand-shipped deploy; suggest locking the published
   deploy if it must stay live.