Skip to content

Deployment Playbook

The full pre-push checklist. copilot-instructions.md carries the headline rule ("don't push without running this"); the depth lives here.

When this applies

Every single push to aguidetocloud-revamp (public Hugo site) or guided (Astro paid product). For the learning portal (this repo), only steps 1–6 + 9 + 12 apply.

The 19 steps (in order)

# Step Why it exists
1 node -c syntax check on every modified JS file. Inline JS gets extracted and checked separately. Multiple production breakages came from a typo that Hugo silently rendered.
2 Hugo build must succeed with zero errors. Use pwsh scripts\hugo-safe.ps1. See Hugo Build Wrapper — never run bare hugo.
3 HTML structure check: div balance, no {{ tokens leaking through, no ZgotmplZ (Hugo's escape sequence for unsafe content). Broken templates render as visible code on production.
4 CSS audit: no duplicate class definitions, new classes don't collide with existing tools (.ptester-* was Policy Tester long before Prompt Tester wanted it). Class collision wiped a tool's styling for 6 hours.
5 cache_version in hugo.toml [params] bumped if any CSS or JS changed. Without this, Cloudflare serves stale assets to returning users.
6 Playwright test against the live site BEFORE deploying. Confirm existing features still work. Deploys often introduce regressions in adjacent code.
7 Playwright test against the deployed site after push. Verifies the fix actually shipped.
8 Never use PowerShell regex to patch JS files. Always edit directly via the edit tool. PowerShell regex on JS has corrupted multiple files (escape mismatches, encoding).
9 One deploy per change. Never batch unrelated changes. A bad deploy bisects to one commit, not five.
10 If something breaks: revert first, investigate second. Don't debug on production. The 30 Apr 2026 practice-exam outage lasted 12h because someone tried to forward-fix instead of reverting.
11 After push, verify pipeline bots can still push. They need git pull --rebase if you've moved ahead of them. AI News, Roadmap, Service Health bots break if the repo HEAD has moved.
12 git pull --rebase before every push. Concurrent sessions push frequently. Rejected pushes waste minutes; rebase is free.
13 Hugo HTML ↔ JS alignment: Hugo renders the HTML, JS manipulates it. Selectors MUST match between them. Renaming a .tool-card class in CSS without updating the querySelectorAll('.tool-card') in JS = silent feature breakage.
14 Fullscreen overlays need position: sticky; top: 0 on the header. Without it, the header scrolls away inside the overlay.
15 Cross-link audit after integration: verify the new tool appears in all ecosystem grids — both the shared partial AND any custom hardcoded grids on specific pages. Tools have shipped invisible because the homepage had a hardcoded list that wasn't updated.
16 Nav count audit: after category changes, verify nav.html <span> counts match. "Tools (47)" when the actual count is 53 is a credibility crater.
17 Frontmatter completeness: _index.md needs real title, description (>50 chars), sitemap.priority, lastmod, images. Missing frontmatter = invisible in Google + broken OG previews.
17.5 SEO + OG image guardrail: run pwsh scripts\check-seo-lengths.ps1 (default: blog only, warn-only). For audits run -All. For local pre-push run -Strict. Also enforced in CI by .github/workflows/seo-check.yml — strict on blog content, warn-only on all content. Long titles/descriptions truncate in Google SERPs. Frontmatter images: referencing missing files breaks Open Graph previews. Built 8 May 2026 after a session-end audit found 14 blog posts over both thresholds — see blog-notebook-system.md Known Issues #2.
18 Guided Quiz blocker: before any push touching PracticeQuiz.tsx, question JSON, or practice.astro, run node test-guided-qa.cjs and require exit code 0. This is a paid product. See the rules in copilot-instructions.md.
19 Parallel-safe git — see Parallel-Safe Git Rules. Never git add . / -A / commit -a. Always explicit paths. The 2 May 2026 cross-session contamination incident.

Pre-deploy checklist (fast version)

[ ] node -c on every modified .js
[ ] hugo build clean
[ ] HTML balance + no {{
[ ] cache_version bumped
[ ] pwsh scripts\check-seo-lengths.ps1 (frontmatter changed?)
[ ] Playwright BEFORE
[ ] git diff --staged shows ONLY my changes
[ ] git pull --rebase
[ ] git push
[ ] Playwright AFTER

Post-deploy: did it actually work?

After Cloudflare Pages reports a successful deploy, run:

# Public site
curl -s https://www.aguidetocloud.com | Select-String "<title>"

# Practice exams (paid product)
curl -s https://www.aguidetocloud.com/guided/data/questions/az-900.json | Select-Object -First 1

# Learning portal
curl -s https://learn.aguidetocloud.com | Select-String "Learning Portal"

If any of these returns HTML instead of expected content, revert before going to bed.

Cross-references