/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.

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).

[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

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):

@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.

[![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):

# 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:

[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.net