Publish locked Netlify production deploys after CI

.github/workflows/ci.yml

@@ -72,15 +72,8 @@ jobs:
       - name: Install dependencies
         run: npm install
 
-      - name: Build app
-        run: npm run build
-
-      - name: Deploy to Netlify
-        run: |
-          deploy_message="$(git log -1 --pretty=%s)"
-          npx --yes netlify-cli deploy --prod --dir=dist --site \
-            "$NETLIFY_SITE_ID" --auth "$NETLIFY_AUTH_TOKEN" \
-            --message "$deploy_message"
+      - name: Publish Netlify production deploy
+        run: npx tsx src/scripts/publish-netlify-production-deploy.ts
         env:
           NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
           NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

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.

netlify.toml

@@ -1,4 +1,3 @@
 [build]
   command = "npm run build"
-  ignore = "[ \"$CONTEXT\" = \"production\" ]"
   publish = "dist/"