netlify-deploy

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.**
   ```bash
   npx netlify status
   npx netlify env:list --context production
   ```
2. **Configure `netlify.toml`** with explicit context overrides:
   ```toml
   [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):
   ```bash
   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:
   ```bash
   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):
   ```bash
   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):
   ```bash
   npx netlify deploy --build --prod \
     --message "release: $(git rev-parse --short HEAD)"
   ```
   Or, to publish an existing preview deploy, use the API:
   ```bash
   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:
   ```bash
   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 |

From SwapnilPopat/ai-assistant-skills, MIT.

More from SwapnilPopat/ai-assistant-skills