git:20260818.03f3dc9 to git:20260819.2693598

53 added, 96 removed. Audit A to A.

---

name: diy-netlify

- description: Build, simplify, audit, or optimize a Netlify/Vercel-style pull-request preview workflow using GitHub Actions and the project's own hosting provider, especially Cloudflare Workers or Pages. Use when every PR should receive an isolated live URL, GitHub status and preview comments, affected-project builds, fast checkout/install/browser steps, safe fork handling, and an uncomplicated merge-to-production path.

+ description: Build or audit an isolated Netlify/Vercel-style pull-request preview workflow using GitHub Actions and the project's existing hosting provider. Use when eligible PRs need separate live preview environments, stable and immutable URLs, GitHub reporting, affected-target builds, and safe fork handling. Do not use for production-bound staged versions, artifact promotion or reuse, or generalized release-platform design.

---

# DIY Netlify

- Reproduce the useful product contract of Netlify Deploy Previews and Vercel

- Preview Deployments without recreating either platform.

- Optimize for one sentence a reviewer can understand:

+ Deliver the reviewer loop people expect from hosted deploy previews without

+ recreating a deployment platform:

> Open a PR, wait for the preview link, review it, merge when green, and let the

> exact merge commit deploy to production.

- ## Deliver the preview product contract

+ ## Preview contract

For each eligible PR:

- 1. Detect the affected deployable targets.

- 2. Build each affected target from the intended PR or merge context.

- 3. Publish it into a preview environment isolated from production.

- 4. Expose a stable PR-scoped URL that updates only after a successful deployment.

- 5. Preserve an immutable deployment identity or URL for the exact build.

- 6. Report pending, success, or failure through a required GitHub check.

- 7. Create or update one concise PR comment with the URL, target, source SHA, and

- deployment status.

- 8. Cancel superseded work for the same PR when the provider and workflow make

- cancellation safe.

- Make preview links shareable with the intended reviewers and add `noindex` where

- the hosting layer does not already do so. Add an optional changed-route entry

- link only when the repository can derive it reliably.

- ## Keep previews separate from production

- For trusted same-repository PRs, use dedicated preview Workers, projects, or

- namespaces with no production routes, domains, secrets, or data/service bindings.

- Use explicit preview-safe configuration rather than filtering production config

- at runtime.

- Require authorization or a separately sandboxed design for forks. Never run

- untrusted fork code with protected credentials merely to match the convenience

- of a hosted preview platform.

+ 1. Detect affected deployable targets conservatively, including shared code and

+ lockfile changes.

+ 2. Build the intended PR or merge context.

+ 3. Publish to an environment isolated from production.

+ 4. Preserve both a stable PR URL and an immutable deployment identity or URL.

+ 5. Maintain one required GitHub check, including a terminal skipped state.

+ 6. Create or update one concise PR comment with target, URL, source SHA, and

+ status.

+ 7. Prevent superseded or stale-head work from replacing a newer preview.

- Treat preview source, preview deployment, merged source, production deployment,

- traffic state, and live behavior as separate facts. Never infer production from

- a successful preview.

+ Add `noindex` when the hosting layer does not already provide it. Add a

+ changed-route entry link only when it can be derived reliably.

- ## Make GitHub Actions boring and fast

+ ## Trust boundary

- Measure recent median, p90/p95, and maximum step times before editing. Optimize

- the demonstrated bottleneck, usually in this order:

+ For same-repository PRs, use dedicated preview Workers, projects, namespaces,

+ and preview-safe configuration. Do not give preview code production routes,

+ secrets, data, or service bindings.

- - Keep affected-target detection fast and conservative for shared code and locks.

- - Keep one required aggregator terminal even when every target is skipped.

- - Use target-specific sparse/blobless checkouts where tests do not require the

- full tree.

- - Install only the selected workspace dependency closure.

- - Use an installed runner browser when the real test supports it; retain a

- suitable local default.

- - Remove package-manager setup from runtime-only scripts.

- - Replace obsolete reconciliation cron jobs with authoritative path triggers and

- manual dispatch.

- - Bound jobs with timeouts derived from healthy tail evidence.

- - Record step time and relevant directory size before adding caches.

+ Exclude forks unless they have a separately authorized, sandboxed publication

+ path. Never expose protected credentials to untrusted workflow code.

- Do not weaken a test to improve its graph. Keep a full checkout when a contract

- really validates the complete media or source tree, or replace it with a

- separately reviewed authoritative inventory.

+ Treat source checks, preview deployment, merged source, production deployment,

+ traffic, and live behavior as separate facts. A successful preview is not

+ production proof.

- Exercise every matrix target on a real runner after changing sparse paths or

- filtered installs. Check for missing manifests, undeclared workspace

- dependencies, runtime-resolution changes, partial-clone lazy fetches, rename

- detection that hydrates blobs, and divergent nested lockfiles.

+ If the requested design intentionally uses production configuration or reuses a

+ staged version for production, this skill no longer applies. Use the relevant

+ production-release and provider guidance instead.

- ## Keep production simple

+ ## Implementation

- On the production branch, build and deploy the exact merged SHA through one

- existing per-target release authority. Verify provider identity/configuration and

- the owning live hostname. Preserve the current rollback boundary.

+ Start from the repository's existing CI and release authorities. Add the

+ smallest affected-target, build, publication, check, and comment changes needed

+ for the preview contract.

- Do not introduce build/stage/promote jobs, artifact handoff, receipt protocols,

- or resumable release states merely because previews now exist. First prove that

- production rebuild waste is frequent and material, artifact transfer is cheaper,

- and cross-run ownership can be fenced. Prefer clearer in-job timing and small

- non-secret receipts.

+ Measure current job and step times before optimizing. Optimize demonstrated

+ bottlenecks without weakening tests. Sparse checkout, filtered installs,

+ runner-provided browsers, caching, and tighter timeouts are optional techniques,

+ not required architecture; exercise every affected matrix target after changing

+ checkout or dependency boundaries.

- Pair with `cloudflare-production-builder` only when changing material production

- traffic, binding, route, migration, promotion, or rollback behavior.

+ Keep production independent: deploy the exact merged SHA through the existing

+ release authority, then verify provider identity and the owning live hostname.

+ Pair with `cloudflare-production-builder` when changing production traffic,

+ bindings, routes, migrations, promotion, or rollback.

- ## Verify the reviewer loop

+ ## Verification

- Use a small visible canary change and prove:

+ Use a small visible canary and prove:

- 1. the correct targets were selected and unrelated ones skipped;

+ 1. affected targets were selected correctly;

2. required source checks passed;

- 3. the PR comment points to the latest successful preview;

- 4. the preview renders the canary on desktop and mobile without production

- bindings or routes;

- 5. merging triggers the exact merge SHA production workflow;

- 6. provider readback and the public hostname report that SHA;

- 7. production smoke checks pass;

- 8. the repository returns to a clean synchronized state.

- Report a timing table with baseline median/tail, canary time, absolute and percent

- delta, and sample size. Mark preview creation as a new capability rather than an

- infinite speedup. Distinguish wall time, runner minutes, tail reliability, review

- experience, and production safety.

- ## Resist platform creep

- Do not build a deployment dashboard, collaboration drawer, branch-environment

- framework, generalized preview database, or multi-provider abstraction until a

- real user need exceeds what GitHub checks, one PR comment, provider URLs, and

- workflow artifacts already provide.

- Read [aiecode2025-case-study.md](references/aiecode2025-case-study.md) for the

- measured rollout that motivated this skill, including the intentionally retained

- full-tree test and the rejected distributed stage/promote redesign.

+ 3. the PR check and comment point to the latest successful preview;

+ 4. the preview renders on the required browser and viewport surfaces;

+ 5. merging triggers production for the exact merge SHA; and

+ 6. provider readback, the public hostname, and production smoke agree.

- Product inspiration:

+ When performance is part of the request, report baseline sample size and

+ median/tail timing alongside the canary result. Distinguish wall time, runner

+ minutes, reliability, review experience, and production safety.

- - [Netlify Deploy Previews](https://docs.netlify.com/deploy/deploy-types/deploy-previews/)

- - [Vercel for GitHub](https://vercel.com/docs/git/vercel-for-github)

+ Do not add a deployment dashboard, generalized preview database,

+ branch-environment framework, multi-provider abstraction, or resumable release

+ controller without a demonstrated product requirement.