netlify-deploy

name	netlify-deploy
description	Deploy static sites, framework apps (Next.js, Astro, Remix, SvelteKit, Nuxt), Edge Functions, and serverless Functions to Netlify with deploy previews, branch deploys, atomic production promotion, scoped env vars, and instant rollback. Use when releasing on Netlify via CLI, API, or Git-triggered builds. Requires NETLIFY_AUTH_TOKEN (PAT) and NETLIFY_SITE_ID.

Netlify Deploy

Release web apps to Netlify with strict preview-to-production gating, environment scoping, and atomic rollback.

Stack Baseline (2026)

Concern	Choice	Notes
CLI	netlify-cli ≥18	npx netlify@latest in CI
Config	netlify.toml at repo root	Build, redirects, headers, plugins, env
Build image	Ubuntu Noble (24.04) default	Set [build.environment] NODE_VERSION = "22"
Functions	Background ≤15 min, sync ≤10 s, scheduled via cron	netlify/functions/*.ts (auto-discovered)
Edge Functions	Deno runtime; declared in netlify.toml [[edge_functions]]	Run at edge before cache
Framework adapters	Next.js Runtime v5 (auto), Astro, SvelteKit, Nuxt, Remix	Auto-detected; pin via @netlify/plugin-nextjs
Env vars	Scoped: builds / functions / runtime / post-processing × deploy contexts (prod/deploy-preview/branch)	Set via UI, CLI, or API
Secrets scanning	Enabled by default; build fails on detected secrets in artifacts	Use env vars, not bundled values
Atomic deploys	Every deploy is immutable; promote/rollback by deploy ID
Auth	Personal Access Token (NETLIFY_AUTH_TOKEN)	Scope per-CI; rotate quarterly

When to Use

• Static-site or framework-app deploys (Next, Astro, SvelteKit, Nuxt, Remix, Hugo, Eleventy).
• Adding Functions / Edge Functions to an existing site.
• Cutting a deploy preview for stakeholder review on every PR.
• Promoting a branch deploy to production after QA sign-off.

Prerequisites

• NETLIFY_AUTH_TOKEN and NETLIFY_SITE_ID exported in CI (no netlify link needed).
• netlify.toml checked in with [build] command, publish dir, and [functions] directory.
• Production env vars (per context) configured: netlify env:set KEY value --context production.
• For framework apps: appropriate Netlify plugin pinned in [[plugins]].

Instructions

1. Verify session and site mapping.

   npx netlify status
   npx netlify env:list --context production
   

2. Configure netlify.toml with explicit context overrides:

   [build]
     command = "npm run build"
     publish = "dist"
     functions = "netlify/functions"
   
   [build.environment]
     NODE_VERSION = "22"
     NPM_FLAGS = "--prefer-offline"
   
   [[plugins]]
     package = "@netlify/plugin-nextjs"
   
   [context.production.environment]
     NEXT_PUBLIC_API_URL = "https://api.example.com"
   
   [context.deploy-preview.environment]
     NEXT_PUBLIC_API_URL = "https://staging-api.example.com"
   
   [[redirects]]
     from = "/api/*"
     to   = "/.netlify/functions/:splat"
     status = 200
   
   [[headers]]
     for = "/*"
     [headers.values]
       X-Frame-Options = "DENY"
       X-Content-Type-Options = "nosniff"
       Referrer-Policy = "strict-origin-when-cross-origin"
       Content-Security-Policy = "default-src 'self'; img-src 'self' data: https:; script-src 'self' 'unsafe-inline'"
   

3. Set/rotate env vars per context (never commit values):

   npx netlify env:set STRIPE_SECRET "$STRIPE_SECRET" --context production --secret
   npx netlify env:set STRIPE_SECRET "$STRIPE_TEST"   --context deploy-preview --secret
   

4. Local quality gates before pushing:

   npm ci
   npm run lint && npm test && npm run build
   npx netlify build  # runs the actual Netlify build pipeline locally
   

5. Cut a deploy preview (no traffic shift; unique URL):

   npx netlify deploy --build --context deploy-preview \
     --message "PR #${PR_NUMBER}: ${COMMIT_SUBJECT}"
   

   Capture the deploy URL and deploy ID from output for verification.
6. Verify the preview end-to-end:
   • Critical routes return expected status & content.
   • Functions logs clean: npx netlify functions:log <name> --tail.
   • OAuth/callback URLs include the preview origin (or use a stable alias).
   • Lighthouse / accessibility checks pass against preview URL.
7. Promote to production atomically (no rebuild — same artifact):

   npx netlify deploy --build --prod \
     --message "release: $(git rev-parse --short HEAD)"
   

   Or, to publish an existing preview deploy, use the API:

   curl -X POST -H "Authorization: Bearer $NETLIFY_AUTH_TOKEN" \
     https://api.netlify.com/api/v1/sites/$NETLIFY_SITE_ID/deploys/$DEPLOY_ID/restore
   

8. Verify production: smoke critical paths, watch function error rate, validate cache headers and edge behavior.
9. Rollback is a single API call to restore any previous deploy ID:

   npx netlify api restoreSiteDeploy \
     --data='{"site_id":"'$NETLIFY_SITE_ID'","deploy_id":"<PREV_DEPLOY_ID>"}'
   

10. Tag the release in your tracker with the Netlify deploy ID for traceability.

Common Pitfalls

Pitfall	Impact	Fix
Setting prod and preview env vars to the same value	Test data hits production systems	Use --context scoping
Missing NODE_VERSION in [build.environment]	Build drifts when default image upgrades	Pin Node version explicitly
Bundling secrets into client bundles	Build fails secrets scanning	Use server-only env vars; whitelist NEXT_PUBLIC_* only
Direct prod deploy without preview	Bad release with no review path	Always preview first; promote artifact
Stale framework plugin	Adapter lags Next/Astro release	Pin @netlify/plugin-nextjs and bump deliberately
Functions exceeding 10 s sync limit	502 to client	Convert to background function or queue
Redirects ordered incorrectly	SPA fallback shadows API routes	Place specific routes before /* catch-all
Forgetting to bust CDN on header-only changes	Old headers cached at edge	netlify deploy always invalidates; verify with curl -I
Using netlify link in CI	Brittle; creates .netlify/state.json	Use NETLIFY_SITE_ID env var instead

Output Format

Report to caller:

1. Deploy ID (preview) and deploy ID (production).
2. Permalink URL and production URL.
3. Env-var diff applied per context.
4. Build log summary: duration, function bundle sizes, plugin output.
5. Post-deploy verification: status of /healthz, function error rate, key routes.
6. Pre-filled rollback command with previous deploy ID.

Authoritative References

• Netlify CLI: https://docs.netlify.com/cli/get-started/
• File-based config (netlify.toml): https://docs.netlify.com/configure-builds/file-based-configuration/
• Environment variables & contexts: https://docs.netlify.com/environment-variables/overview/
• Deploy contexts: https://docs.netlify.com/site-deploys/overview/#deploy-contexts
• Functions: https://docs.netlify.com/functions/overview/
• Edge Functions: https://docs.netlify.com/edge-functions/overview/
• Rollbacks (restore deploy): https://docs.netlify.com/site-deploys/manage-deploys/#rollbacks