Document Netlify deployment flow

Record the locked auto-publishing invariant and explain why GitHub Actions publishes Netlify-built production deploys.

Author: john-kurkowski

README.md

@@ -16,6 +16,13 @@ Install Playwright browsers only if you plan to run browser-based tests locally.
 
     npm start
 
+## Deployment
+
+Netlify builds deploy previews, branch deploys, and production deploys.
+Production auto publishing is locked in Netlify; GitHub Actions publishes the
+matching production deploy after CI passes. See [Deployment](docs/DEPLOYMENT.md)
+for the full production flow.
+
 ### Tests
 
     npm test

docs/DEPLOYMENT.md

@@ -0,0 +1,39 @@
+# Deployment
+
+This site intentionally separates CI from production publishing.
+
+Netlify owns the builds. GitHub Actions owns the production publishing gate.
+Auto publishing must stay locked in Netlify so production deploys can be built
+without going live before CI passes.
+
+## Deploy Flow
+
+- Pull requests get Netlify Deploy Previews through Netlify's Git integration.
+- Non-production branches get Netlify branch deploys, depending on the site's
+  branch deploy settings in Netlify.
+- Pushes to `master` create Netlify production deploys, but Netlify does not
+  publish them automatically while auto publishing is locked.
+- After GitHub Actions checks pass on `master`, the production deploy job finds
+  the Netlify production deploy for the same commit SHA and publishes that
+  deploy.
+
+## Production Invariants
+
+- Keep Netlify builds active.
+- Keep Netlify auto publishing locked.
+- Do not replace the GitHub Actions publish step with an artifact upload unless
+  production should stop exercising Netlify's build environment.
+- Do not publish a Netlify deploy unless its commit SHA matches the GitHub
+  Actions run that passed CI.
+
+## Troubleshooting
+
+If production does not publish after CI passes:
+
+- Check the GitHub Actions production deploy job logs.
+- Confirm `NETLIFY_AUTH_TOKEN` and `NETLIFY_SITE_ID` are available to GitHub
+  Actions.
+- Confirm Netlify has a production deploy for the same commit SHA.
+- Confirm the matching Netlify deploy reached the `ready` state.
+- Confirm Netlify auto publishing is still locked; the workflow publishes one
+  matching deploy and does not unlock future automatic publishing.

src/scripts/publish-netlify-production-deploy.ts

@@ -1,5 +1,12 @@
 #!/usr/bin/env -S npx tsx
 
+/**
+ * Publish the Netlify-built production deploy that matches the current GitHub
+ * Actions commit. Netlify owns the build because production should exercise the
+ * same platform path as deploy previews and branch deploys; GitHub Actions owns
+ * the publish gate so production only changes after CI passes.
+ */
+
 import { pathToFileURL } from "node:url"
 
 type Fetch = typeof fetch
@@ -52,6 +59,11 @@ const pendingStates = new Set([
 
 const terminalFailureStates = new Set(["error", "rejected"])
 
+/**
+ * Poll Netlify for the production deploy that matches CI's commit, then publish
+ * it once it is ready. This keeps the workflow from publishing an older or
+ * unrelated deploy while Netlify auto publishing is locked.
+ */
 export async function publishNetlifyProductionDeploy(
   options: PublishOptions,
   dependencies: Partial<Dependencies> = {},
@@ -102,6 +114,11 @@ export async function publishNetlifyProductionDeploy(
   )
 }
 
+/**
+ * Select the Netlify production deploy for the exact branch and commit. The
+ * explicit match is necessary because Netlify may list deploys from other
+ * branches, contexts, or nearby commits while CI is waiting.
+ */
 export function findMatchingDeploy(
   deploys: NetlifyDeploy[],
   options: Pick<PublishOptions, "branch" | "commitRef">,
@@ -205,6 +222,11 @@ function readPositiveIntegerEnv(name: string, fallback: number): number {
   return parsed
 }
 
+/**
+ * Read the GitHub Actions and Netlify settings needed by the publish job.
+ * Keeping this at the CLI boundary lets tests exercise the deploy logic without
+ * depending on process environment state.
+ */
 export function readOptionsFromEnv(): PublishOptions {
   return {
     authToken: readRequiredEnv("NETLIFY_AUTH_TOKEN"),