netlify-deploy

Files (4)

• SKILL.md
• cli-commands.md · references/
• deployment-patterns.md · references/
• netlify-toml.md · references/

SKILL.md (first lines)

# Netlify deploy

## Modern CLI

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

```toml
[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 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:
```md
[![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`):
```txt
# 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`:
```toml
[template]
  incoming-hooks = ["Contentful"]
  required-extensions = ["supabase"]

[template.environment]
  SECRET_TOKEN = "change me for your secret token"

From netlify/context-and-tools, MIT.

More from netlify/context-and-tools