/netlify-deploy

name: netlify-deploy
description: Create, configure, and manage Netlify deploys from code — reach for this when setting up Git continuous deployment, running netlify deploy or netlify deploy --prod from the CLI, writing netlify.toml deploy contexts, adding a Deploy to Netlify button, wiring build hooks, configuring Deploy Previews or branch deploys, locking or skipping deploys, fixing a failed or secrets-scanning deploy, or when someone asks to "deploy my site", "set up preview deploys", "add per-branch build config", "keep staging out of Google", or "add a deploy button to my README".

Netlify deploy

Modern 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+

A deploy is a versioned, **atomic** snapshot: Netlify uploads only changed files and switches the live site only after all files land — the site is never in an inconsistent state. A deploy can be a preview or a production version served at your primary domain.

**Continuous deployment vs manual deploys:** Deploy with Git and the Netlify CLI support continuous deployment — a push auto-triggers a build. Drag and drop and the API create one-off manual deploys. Manual deploys (`netlify deploy`) do **not** run a build command; drag-and-drop while logged in is the only exception (framework auto-detected).

**⚠ When linking or creating a site, add `.netlify` to `.gitignore`.** Every linking path writes `.netlify/state.json`, which must not be committed.

Ways to create a deploy

• **Git CD** — connect a repo; Netlify builds and deploys on every push (OAuth2 or the Netlify GitHub App). This is the default path. Production deploys come from pushes to the production branch — often the repo's default branch (e.g. `main`), changeable under Branches and deploy contexts.
• **CLI** — `netlify create`, `netlify deploy`, `netlify deploy --prod`.
• **Drag and drop** — https://app.netlify.com/drop. Logged in: builds if needed. Not logged in: publishes files as-is.
• **API** — create deploys via file digest or ZIP (one-off manual).
• **Deploy to Netlify button** — one-click from a public template repo.
• **Build hooks** — unique URLs that trigger builds. (Deploys from build hooks are treated as trusted and bypass the deploy request policy.)
• **AI agents** — Agent Runners (Claude Code, OpenAI Codex, Google Antigravity, Meta Muse) from the dashboard; every file-changing run auto-generates a Deploy Preview at `agent-<runID>--<site>.netlify.app`. The inline preview shown next to the prompt is the same Deploy Preview available at that URL.
• **Zapier / n8n** — automation integrations.

Not sure which path? The Deploy Navigator gives personalized recommendations: https://docs.netlify.com/start/choose-your-path#deploy-navigator (also embedded on the create-deploys page as "Not sure where to start?").

netlify.toml deploy contexts

At the repo root. File config overrides UI settings. Five predefined contexts: `production`, `deploy-preview`, `branch-deploy`, `preview-server`, `dev`. Branch names also work as custom contexts; more specific contexts override general ones.

[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"

**⚠ Environment variables set in `netlify.toml` are NOT available to the deploy environment** — set them via UI/CLI/API. `netlify.toml` is committed, so keep sensitive values out of it; use per-context env vars via UI/CLI/API instead.

See `references/netlify-toml.md` for the full context precedence rules and `references/deployment-patterns.md` for context strategy.

Deploy Previews & branch deploys

• **Deploy Previews** auto-build for PRs/MRs (GitHub, GitLab, Bitbucket, Azure DevOps, Cursor Origin) and agent runs. The base branch must be a production branch or a branch-deploy-enabled branch. URL: `deploy-preview-<num>--<site>.netlify.app`. While the first deploy is pending the URL returns `Not Found`.
• **Branch deploys** require setup: Project configuration > Developer settings > Continuous deployment > Branches and deploy contexts > Configure. Enable specific branches (prefix wildcard `features/*` supported) or **All** new branches. URL: `<branch>--<site>.netlify.app`. A branch deploy persists as long as the branch exists. Build settings/env vars: `[context.branch-deploy]` for all branches, `[context.<branch>]` for one.
• A branch-deploy branch with an open PR yields **both** a Deploy Preview and a branch deploy.
• **Entry path:** put `@netlify /some/path` in the PR/MR description, then push a new commit to regenerate. Once set in the PR, you can't change it in the Netlify Drawer.
• **Skip a deploy:** `[skip ci]` or `[skip netlify]` — in the PR/MR **title** to skip the Deploy Preview; **anywhere in the commit message** to skip a branch/production deploy. Next unmarked commit deploys all skipped changes.

Locking, skipping, and manual production deploys

• **Lock** (disable auto publishing): Deploys list > **Lock to stop auto publishing**. New deploys still build but are not published. Unlock to resume.
• **⚠ Manual `netlify deploy --prod` on a Git-CD site:** the next push to the production branch silently replaces your h