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)

Netlify only builds changes pushed to private repos from recognized authors (Owners, Developers, Git Contributors; Marketplace bots count). An unrecognized author's merge shows Pending approval; a Team Owner must associate them with a team account before the build starts. Build-hook deploys are exempt.

Constraints & gotchas

• Files per directory: 54,000. Any directory over this in the publish dir fails the deploy. No limit on total files per deploy.
• Skew protection: all plans; production context only — branch deploys, Deploy Previews, and permalinks bypass it and serve the latest deploy. Needs Netlify CLI 23.11.0+. Astro 5.15.0+ enables it by default via the Netlify Adapter; Next.js is opt-in. Password protection on production deploys (or on all deploys) turns skew protection off — it only works when you protect non-production deploys only. Netlify discards skew protection signals on hard navigation (Sec-Fetch-Mode: navigate, or Sec-Fetch-Site present and not same-origin). Framework maintainers add support via netlify/v1/skew-protection.json.
• Search indexing: only the published production deploy and most recent branch deploys are indexable; previews and old deploys get X-Robots-Tag: noindex.
• Preview URL visibility: Deploy Preview / branch deploy URLs are shareable with anyone holding the link unless you add password or team-login protection.
• New-project visibility: on Credit-based plans with "private by default", new projects start private regardless of how they're created.
• Automatic deletion: deploys are deleted after 30 days (90 days on paid plans); Enterprise can raise this up to 365 days. Never deleted: the published deploy, the most recent successful production deploy, and the most recent successful branch deploy per branch. Configure at Project configuration > Developer settings > Automatic Deletion.

See references/cli-commands.md for the full CLI surface and flags.

<!-- Retention period for failed/canceled deploys is stated inconsistently in sources (30/90 days vs 6 months); used the 30/90-day figure. --> <!-- 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.
9. Deploy-to-Netlify buttons: template configuration (incoming hooks, template env vars) is only read from the repository ROOT. When a button targets a subdirectory via base, state this limitation explicitly — do not leave it implied.