Netlify Deploy

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. 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.
• 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.
• 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 Gemini) from the dashboard; every file-changing run auto-generates a Deploy Preview at agent-<runID>--<site>.netlify.app.

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]
  command = "make staging"

[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 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 hand-shipped deploy. Warn the user; lock the published deploy if it must stay live.

Managing deploys

• Find: Deploys tab (Developer or Team Owner); search by deploy ID or branch name; filter by time frame, deploy context, and status.
• Cancel: on the in-progress deploy's detail page, Cancel deploy > Yes, cancel deploy.
• Retry: builds from the branch HEAD (optionally clearing cache) — if HEAD moved past the original deploy SHA, it still builds from HEAD.
• Download: on a successful deploy's detail page — a single file via Deploy file browser, or all files as a ZIP via the header Download > Download ready.
• Delete: Developer or Team Owner only. You cannot delete the deploy most recently published to the site's main URL, or one still in progress. Deletion is permanent and does not reduce team costs or preserve build minutes.

Deploy to Netlify button

Template code must be in a public repo on GitHub.com or 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 variants (base link 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

File-based template config, [template] in the repo root netlify.toml:

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

You cannot set env var values or a base directory in [template] — use URL params. [template.environment] placeholder strings are only UI labels.

⚠ Template configuration (incoming hooks, template env vars) is read ONLY from the repository ROOT. When the button targets a subdirectory via base, the base-directory netlify.toml takes precedence for builds, but template config there is ignored. State this limitation explicitly rather than leaving it implied.

Secrets scanning failures

⚠ A secrets-scanning deploy failure means a value that looks like a secret reached your build output. If it's a real secret, that's a leak — stop shipping it in client/published output and rotate it. Never set SECRETS_SCAN_ENABLED=false to silence the scanner over a real leak. For genuinely non-secret values, scope narrowly with SECRETS_SCAN_OMIT_KEYS / SECRETS_SCAN_OMIT_PATHS.

Fixing a failed deploy — no rollbacks

A failed deploy never publishes — the previous deploy is still live, so there is nothing to restore. If someone asks to roll back or restore a previous deploy, correct the premise: after a failed deploy nothing changed, and for a bad published deploy, fix forward — revert the commit and let CI redeploy it. Do not call restoreSiteDeploy or publishDeploy, and do not hand over a dashboard rollback as the answer.

Netlify surfaces a "Why did it fail?" AI diagnosis above the deploy log. See https://docs.netlify.com/resources/troubleshooting/fix-a-failed-deploy/.

Deploy permissions (private repos)