@andwhy/e2e-pipeline 0.10.0

package/templates/claude/rules/playwright-workflow.md

@@ -0,0 +1,203 @@
+# Playwright Agent Workflow
+
+> Setup and day-to-day workflow docs (for humans): https://app.notion.com/p/31ff837b6270805d8922c4a7c7beb6b0
+
+When the user says "Use the playwright-test-planner/generator/healer agent", always delegate via the Agent tool with the matching subagent_type (`playwright-test-planner`, `playwright-test-generator`, `playwright-test-healer`). Never attempt to call the MCP tools directly.
+
+**Do not implement Playwright specs in the orchestrating turn.** Writing or editing `*.spec.js` test bodies yourself bypasses replay, generator MCP tools, and project rules. For generation, always use the **Agent** tool with `subagent_type: "playwright-test-generator"`.
+
+**Plans:** Read `tests/e2e/<feature>/<name>.plan.md` yourself and pass its contents in the Agent prompt. **Never ask the user to paste the plan** into chat.
+
+## Agents
+
+| Trigger phrase in user prompt                  | `subagent_type`             | Purpose                                                                                                                             |
+| ---------------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| "Use the playwright-test-planner agent to …"   | `playwright-test-planner`   | Explores the live site, discovers real selectors/DOM, writes a `tests/e2e/<name>.plan.md`                                           |
+| "Use the playwright-test-generator agent to …" | `playwright-test-generator` | Reads a plan, replays steps in a browser, writes or extends `tests/e2e/<group>.spec.js` or `.spec.ts` (**Project test rules** §7–8) |
+| "Use the playwright-test-healer agent to …"    | `playwright-test-healer`    | Runs tests, debugs failures, fixes code, re-runs until green                                                                        |
+
+## Project test rules
+
+These rules apply to **all** agents (generator, healer, and orchestrator). Include them in every Agent prompt to the generator or healer.
+
+1. Every logical step MUST have a numbered comment above it
+   (e.g. `// 1. Navigate to the homepage`). Preserve existing step comments
+   when editing. Add them if missing.
+
+2. Never hardcode domains. Use `page.goto("/")` and derive the origin from the
+   live page URL.
+
+3. Every `test.describe` block MUST include a `beforeEach` that runs shared preview setup
+   from `tests/e2e/helpers/preview-consent-setup.js` or `.ts` (`prepareVercelPreviewPage`, and when tests
+   start after consent, `gotoPathAndAcceptCookies(page, baseURL, path)` with the correct
+   relative path). The scaffold ships `prepareVercelPreviewPage` — it exchanges
+   `VERCEL_AUTOMATION_BYPASS_SECRET` for Vercel's deployment-protection bypass cookie on the
+   first navigation and is a plain `goto` when the variable is unset. Extend the file with
+   project consent logic; do not reinvent it. The helper file extension must match rule 7.
+
+4. Never hardcode a single locale's URL pattern. Use a locale config map keyed
+   by bare hostname and resolve at runtime.
+
+5. After all tests pass locally, verify with
+   `BASE_URL=<dev-url> pnpm playwright test` via the terminal tool. If failures
+   occur, fix and re-run until green.
+
+   **Local runs always pin `BASE_URL` on the command line** to the dev server
+   confirmed during setup (usually `http://localhost:3000`) — never rely on the
+   ambient environment. Repos commonly export `BASE_URL` for the app's own
+   purposes, pointed at the deployed site; an unpinned run silently targets
+   production, which does not contain the working tree's changes (the feature
+   under test, any `data-testid` additions). Deployed URLs enter the pipeline
+   only at preview validation and Checkly, always passed explicitly.
+
+6. **Test root:** Paths in this file assume the default `tests/e2e/`, which keeps e2e specs
+   clear of unit tests in the same repo. **The repo wins over this default.** Check
+   `playwright.config.{ts,mjs}` for `testDir` and list existing `*.spec.*`; if the **e2e**
+   specs already live somewhere else (`tests/` flat, `e2e/`, `src/__tests__/`), write there
+   instead and read every `tests/e2e/…` path below as that directory. Never split a suite
+   across two roots. A non-e2e suite under `tests/` (unit, a11y) is **not** that signal:
+   leave `testDir` on the e2e root and give that suite its own Playwright project with its
+   own `testDir` — never widen `testDir` to cover both, which runs the other suite in every
+   browser project.
+
+7. **Spec language (generators only):** Repositories differ — some teams use **JavaScript**
+   for Playwright tests (`.spec.js`), others use **TypeScript** (`.spec.ts`). List
+   `tests/e2e/**/*.spec.*` and match the prevailing extension. If there are no specs yet, default
+   to `.spec.js` unless the project README or the user specifies TypeScript for tests. Helpers
+   and seeds must use the same language as specs. Do not add `.spec.ts` in a repo that already
+   uses `.spec.js` everywhere (and vice versa).
+
+8. **Feature groups (target layout):** Prefer **one spec file per feature group** (e.g.
+   `tests/e2e/map/map.spec.js`) with a single `test.describe('<Group name>', …)` and **multiple**
+   `test()` blocks — one per plan scenario — sharing one `beforeEach`. Do not default to one
+   file per scenario unless scenarios are unrelated. Prefer **lean** tests: assert user-visible
+   outcomes and regressions, not every intermediate DOM detail from the plan. Numbered
+   comments on **main** user steps only.
+
+## Pipeline: Plan → Generate → Heal
+
+### Step 1 — Plan
+
+Trigger when: user wants to create tests for a new feature, page, or user flow.
+
+1. Use the **Agent** tool with `subagent_type: "playwright-test-planner"`
+2. Pass the URL and user flow description in the `prompt`
+3. The planner saves output to `tests/e2e/<name>.plan.md`
+4. When the subagent returns, present the plan to the user for review before proceeding
+
+Prompt to forward:
+
+```
+Create a test plan for: <FEATURE NAME>
+
+Navigate to <URL> and explore the following user flow:
+<USER'S FLOW STEPS>
+
+While exploring, verify:
+- Actual selectors (see **Locator strategy** under *Robustness patterns* below)
+- Whether cookie consent or login gates appear
+- DOM structure of key interactive elements
+- If the suite targets **multiple domains**, explore **each** domain the tests will run against
+  (see *Multi-domain / multi-locale testing* — the plan must reflect every distinct host or market)
+
+Generate a seed file at tests/e2e/<feature>/seed.spec.js or seed.spec.ts (same extension as
+the rest of this repo's specs — see Project test rules §7) that handles the common setup
+(navigation, cookie/auth consent, waiting for key elements) discovered during exploration.
+
+Save the plan to tests/e2e/<feature>/<name>.plan.md using planner_save_plan.
+All URLs must use relative paths — never localhost or absolute domains.
+```
+
+### Step 2 — Generate
+
+Trigger when: a `tests/e2e/<name>.plan.md` exists and the user wants generated test code.
+
+**You (the orchestrating agent) own this step end-to-end.** The human does **not** need to
+invoke the generator separately for each scenario or plan section — you chain **Agent** calls
+to `playwright-test-generator` until the feature group is implemented (see **Important rules**).
+
+1. Read `tests/e2e/<name>.plan.md` to get the full plan content
+2. Use the **Agent** tool with `subagent_type: "playwright-test-generator"` — **once per scenario**
+   if building incrementally, **or** pass the **full plan** and all scenarios for the group in one
+   prompt if the generator can emit the whole file (**Project test rules** §8)
+3. Pass the **plan content** in the `prompt` (the generator subagent cannot read arbitrary paths from disk)
+4. Include the **project test rules** above in the prompt
+5. If the plan contains a "Recommended data-testid additions" table, include it — the generator adds those attributes before replaying steps
+6. Target **one spec file per feature group** (e.g. `tests/e2e/map/map.spec.js`) with a shared
+   `test.describe` and **multiple** `test()` blocks — merge with `edit` between runs if needed
+
+Prompt to forward (example — adjust per repo):
+
+```
+Implement tests from the plan for this feature group. Target layout: one file, one describe, multiple tests (see project test rules §8).
+
+- Group / describe: "<TOP-LEVEL PLAN HEADING e.g. Map>"
+- File: tests/e2e/<feature>/<group>.spec.js (or `.spec.ts` per project)
+- Seed: <SEED FILE PATH FROM PLAN>
+- Viewport: <WIDTH>x<HEIGHT>
+
+<plan>
+<PASTE full plan OR the scenario block(s) you are implementing this run>
+</plan>
+
+If recommended data-testid additions exist, add them to source components before replaying steps.
+
+After the spec is written or updated, run
+BASE_URL=<dev-url> pnpm playwright test tests/e2e/<feature>/ (pin the dev server per rule 5).
+```
+
+### Step 3 — Heal
+
+Trigger when: tests are failing (after generation, after site changes, or on user request).
+
+1. Use the **Agent** tool with `subagent_type: "playwright-test-healer"`
+2. Pass the test file path in the `prompt`
+3. Include the **project test rules** above in the prompt so the healer follows them
+
+Prompt to forward (always include the rules block):
+
+```
+Run and fix the tests in tests/e2e/<name>.spec.js (or `.ts` per project)
+
+If any tests fail:
+
+- Debug each failure
+- Examine the page state, selectors, and assertions
+- Fix the test code
+- Re-run until all tests pass locally
+
+## Project test rules (follow these strictly)
+
+<COPY the Project test rules section above into this prompt>
+```
+
+## Important rules
+
+- **Always delegate via the Agent tool.** Never call `playwright-test/*` tools directly.
+- **Always plan before generating.** Use the planner to discover real selectors first.
+- **Always read the plan file** before passing to the generator. The generator runs in
+  isolation — include the plan or scenario steps in the prompt.
+- **You implement the full generate phase.** After plan approval, **you** invoke the
+  generator subagent **as many times as needed** (typically once per scenario, sequentially)
+  or supply the full multi-scenario prompt — **without** asking the user to run the generator
+  for each plan section. A single user request such as "Implement the tests from this plan" is enough.
+- **Run generator subagent calls sequentially.** Never parallel — the MCP browser server is shared.
+- **Do not interrupt.** Sending a message while a generator is running aborts it.
+  Wait for completion before proceeding.
+- **data-testid additions are owned by the generator.** When the plan includes a
+  "Recommended data-testid additions" table, the generator subagent adds those
+  attributes to source components before replaying steps. The orchestrator must
+  forward the table verbatim in the generator prompt and must NOT edit source
+  components itself.
+- **Present the plan for review** after planning. Unless the user narrows scope, **proceed
+  to generate all scenarios** for the agreed feature group (see **Project test rules** §8).
+- **Generator and healer self-verify locally** with
+  `BASE_URL=<dev-url> pnpm playwright test` (pinned per **Project test rules** §5).
+  Cloud validation via `checkly pw-test` is a separate human step after pushing.
+  Only invoke the healer if a generated test fails locally.
+- **Base URL**: local runs pin `BASE_URL=<dev-url>` on the command (**Project
+  test rules** §5); the config's localhost fallback is a safety net, not a
+  guarantee, because an exported `BASE_URL` overrides it silently.
+- **Plan files** are saved at `tests/e2e/<feature>/<name>.plan.md`.
+- **Test files** follow **Project test rules** §7–8 — typically `tests/e2e/<feature>/<group>.spec.js`
+  or `.spec.ts` with one `describe` and multiple tests.

package/templates/claude/skills/playwright-test-pipeline/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: playwright-test-pipeline
+description: Guides the full workflow for creating and maintaining Playwright
+  end-to-end tests with the planner/generator/healer agents — setup check,
+  Plan → Generate → Heal, local runs, Checkly preview validation, and
+  deployment. Use when the user wants to create, extend, or fix e2e/Playwright
+  tests, asks to "test" a page/feature/flow, or asks how the test pipeline
+  works.
+---
+
+# Playwright Test Pipeline
+
+You are guiding a person through this project's test pipeline. They may not
+know it exists — narrate briefly at each phase, and pause at the marked
+decision points. The delegation rules and prompt templates live in
+`.claude/rules/playwright-workflow.md` (already in your context); follow them,
+do not improvise your own prompts to the agents.
+
+## Phase 0 — Setup (always first)
+
+Verify, in order:
+
+1. `.claude/agents/playwright-test-planner.md` (and generator/healer) exist
+2. `.mcp.json` at project root defines the `playwright-test` server, pointed
+   at `playwright.mcp.config.{ts,mjs}` (which must exist — it lets the MCP run
+   seeds that `testIgnore` hides from normal runs)
+3. A `playwright.config.{ts,mjs}` and `checkly.config.{ts,mjs}` exist
+
+### If anything is missing, install it — do not just bounce the user
+
+Say what is missing, then offer to run the scaffold. Do not run it without
+agreement: it installs dependencies and writes files.
+
+**Always pass `--format` explicitly.** Without it the CLI opens an interactive
+prompt, and in a non-interactive shell that prompt resolves empty and the CLI
+exits silently having done nothing — it looks like it worked. Pick the format
+from the repo: `ts` when there is a `tsconfig.json`, otherwise `mjs`.
+
+```bash
+pnpm dlx @andwhy/e2e-pipeline init --format ts    # or --format mjs
+```
+
+Add `--force` only when updating an existing install. It regenerates
+`.claude/**` and `.mcp.json` and never touches the configs.
+
+Then read the output back to the user: what was created, what was skipped.
+Docs: https://app.notion.com/p/31ff837b6270805d8922c4a7c7beb6b0
+
+**After a mid-session install, a restart is required — this is a hard stop.**
+Claude Code registers subagents and `.mcp.json` servers at session start, so
+the planner/generator/healer and the `playwright-test` browser tools do not
+exist in the session that just scaffolded them. Do NOT work around this:
+no inlining an agent definition into a general-purpose agent, no hand-writing
+plans or specs from source code — without the browser tools that produces
+unverified selectors, which is exactly what this pipeline exists to prevent.
+Finish Phase 0 (configs, reachable URL), then tell the user to restart the
+session and re-ask; Phase 0 will pass and planning starts for real.
+
+### Then finish the configuration before planning
+
+The scaffold writes templates, not a working setup. Walk these with the user:
+
+1. `playwright.config` — `baseURL` for local runs.
+2. `checkly.config` — real `projectName` and `logicalId`, the production
+   domain(s) in `environmentVariables`, `testCommand` (see Phase 5), and the
+   check-suite `name` — that is what teammates see in the Checkly dashboard
+   and in alerts. **Ask the user what to call it** unless the repo makes it
+   obvious (a single clear brand or product name); do not silently invent
+   one. Also set
+   `installCommand: "pnpm install --ignore-scripts"` — Checkly's runner gets a
+   bundle of test files, not the repo, so a project postinstall (codegen etc.)
+   fails there on missing files. Placeholder values (`my-app`, `example.com`)
+   left in place will block Phase 4; local work is unaffected.
+3. A reachable URL for the planner: a running dev server or a deployed
+   environment. **Confirm this before Phase 1** — the planner explores a live
+   page, and pointing it at an empty or unreachable app produces a plan that
+   asserts nothing useful.
+4. **Repository secrets for the workflows**: if the scaffold just created
+   `.github/workflows/`, tell the user now — not at merge time — to add three
+   repository secrets (GitHub → Settings → Secrets and variables → Actions).
+   You cannot add them; a person must. Without them the first PR push and the
+   first merge fail CI in ways that look like pipeline bugs.
+   - `CHECKLY_API_KEY` — 1Password ("Checkly") first; else Checkly → User
+     Settings → API keys. The key is shown once, at creation — tell the user
+     to save it to 1Password immediately.
+   - `CHECKLY_ACCOUNT_ID` — Checkly → Account Settings → General; also in
+     1Password.
+   - `VERCEL_AUTOMATION_BYPASS_SECRET` — Vercel → project → Settings →
+     Deployment Protection → Protection Bypass for Automation. Per project —
+     never copied from another repo.
+5. **Existing tests under `tests/`** (unit, a11y — the scaffold lists them as
+   "outside tests/e2e"): leave `testDir` at `./tests/e2e` and give that suite
+   its own Playwright project with its own `testDir` if it should run under
+   Playwright at all. **Never widen `testDir` to `./tests`** — that runs the
+   other suite in every browser project and mixes the suites. Checkly is
+   pinned to `tests/e2e` by `testCommand` either way.
+
+## Phase 1 — Plan
+
+1. Ask, if not already clear: which page/flow, which URL, and whether the
+   suite targets multiple domains (check `checkly.config` for the list).
+2. Delegate to `playwright-test-planner` using the rules-file template.
+3. **Decision point:** present the saved plan (`tests/e2e/<feature>/<name>.plan.md`)
+   scenario-by-scenario and ask what to keep, drop, or adjust. Do not
+   generate before the user responds.
+
+## Phase 2 — Generate
+
+1. Read the plan file yourself; never ask the user to paste it.
+2. Delegate to `playwright-test-generator` per the rules file (sequential
+   calls, project test rules included, data-testid table forwarded verbatim).
+3. Tell the user which spec file is being written and when each scenario lands.
+
+## Phase 3 — Run and heal
+
+1. Run `BASE_URL=<dev-url> pnpm playwright test tests/e2e/<feature>/`, pinning
+   the dev server confirmed in Phase 0. Phases 1–3 always target local: the
+   working tree's changes (the feature, any `data-testid` additions) exist
+   nowhere else, and an ambient `BASE_URL` export would silently point the run
+   at the deployed site. Deployed URLs enter only at Phase 4, always explicit.
+2. Green → Phase 4. Red → delegate to `playwright-test-healer` per the rules
+   file. If the healer marks anything `test.fixme()`, surface it explicitly —
+   the user decides whether that is acceptable.
+
+## Phase 4 — Preview validation (before merge)
+
+1. Auth check (first authenticated command in the pipeline): run
+   `pnpm checkly whoami`. If not logged in, have the user run
+   `pnpm checkly login` — it opens a browser flow, and the shared team
+   credentials are in 1Password (search "Checkly"). Local Playwright runs
+   never need this, and CI does not either — it uses the `CHECKLY_API_KEY` /
+   `CHECKLY_ACCOUNT_ID` repository secrets.
+2. **Decision point:** ask for the preview deployment URL, and settle how
+   Checkly's runners get through Vercel deployment protection. Preferred: the
+   project's automation bypass secret (Vercel project settings → Deployment
+   Protection; value in 1Password) — the scaffolded helper exchanges it for
+   Vercel's bypass cookie on first navigation. Fallback when the project has
+   no secret: a share link ("Anyone with the link") as the preview URL.
+3. Run: `pnpm checkly pw-test --env BASE_URL="<preview-url>" --env VERCEL_AUTOMATION_BYPASS_SECRET="<secret>" -- tests/e2e/<feature>/`
+   (omit the second `--env` on the share-link fallback). Never write the
+   secret into `checkly.config` — deployed monitors run against production
+   and do not need it.
+4. Failures here but not locally are usually cloud-environment issues
+   (timeouts, consent gates) — heal with that framing, then re-run.
+
+The user can skip this phase; note that cloud behavior then goes unverified
+until after merge.
+
+## Phase 5 — Merge and deployment
+
+The scaffold ships two workflows (seeded once — existing ones are never
+overwritten):
+
+- `.github/workflows/pr-playwright-tests.yml` — runs the suite against the
+  PR's own Vercel preview on every push (`deployment_status` trigger, so the
+  preview is already live and contains the PR's changes), and comments the
+  result on the PR.
+- `.github/workflows/checkly-deploy.yml` — when a **production deployment
+  succeeds** (`deployment_status` trigger), deploys the checks as Checkly
+  monitors. Not on merge: monitors must match what production serves, and a
+  merge that adds tests for new `data-testid`s would go red until the release
+  carrying them is live — with gated releases that gap can be days. A
+  `workflow_dispatch` fallback allows manual runs.
+
+**Before the first merge, the repo needs secrets** (values in 1Password):
+`CHECKLY_API_KEY` and `CHECKLY_ACCOUNT_ID` for the deploy,
+`VERCEL_AUTOMATION_BYPASS_SECRET` for the PR run through deployment
+protection. If the scaffold just created the workflows, say so explicitly and
+list the three secrets — a merge without them fails CI and looks like a
+pipeline bug.
+
+After merge, monitors update once the production deployment goes live — the
+user verifies in the Checkly dashboard (https://app.checklyhq.com/); nothing
+to run by hand. Manual fallback if a repo deleted the deploy workflow:
+`pnpm checkly test --record`, then `pnpm checkly deploy` (requires the
+Phase 4 login).
+
+**Alert notifications are not automatic — walk the user through it.** A
+failing monitor only shows in the Checkly dashboard until an alert channel
+exists, so nobody gets notified. In Checkly:
+
+1. Alert channels → "Add more channels" → select **Slack**.
+2. Channel configuration: the project's Slack notification channel
+   (`#…`). A dedicated test-notification channel may exist by now — ask
+   which channel to use rather than assuming.
+3. Verify the subscriptions: **only the current check** subscribed, and
+   **uncheck** "Automatically subscribe newly created checks to this alert
+   channel".
+4. Test the alert channel (button) and confirm the notification arrived in
+   Slack.
+5. "Create alert Slack channel".
+
+## Conventions to uphold
+
+The generator and healer enforce spec-level rules themselves. At the pipeline
+level, additionally keep to:
+
+- One spec file per feature group; one `describe`, multiple `test()` blocks
+- Commit specs, plans, seeds, **and** any `data-testid` source edits together
+- Never commit with locally failing tests — heal first or `test.fixme()` with
+  the user's sign-off

package/templates/github/scripts/playwright-pr-comment.mjs

@@ -0,0 +1,95 @@
+// Renders a Playwright JSON report as a PR comment body on stdout.
+import { readFileSync } from 'node:fs'
+
+const MARKER = '<!-- playwright-preview-report -->'
+const { PREVIEW_URL = '', RUN_URL = '' } = process.env
+
+const truncate = (text, max) =>
+  text.length > max ? `${text.slice(0, max)}…` : text
+
+// Strips the ANSI colour codes Playwright writes into JSON error messages.
+const clean = text =>
+  String(text ?? '')
+    .replace(/\u001b\[[0-9;]*m/g, '')
+    .trim()
+
+const collect = (suite, acc = []) => {
+  for (const spec of suite.specs ?? []) {
+    for (const test of spec.tests ?? []) {
+      const last = test.results?.[test.results.length - 1]
+      if (!last || ['passed', 'skipped'].includes(last.status)) continue
+      acc.push({
+        title: spec.title,
+        file: spec.file ?? suite.file,
+        line: spec.line,
+        status: last.status,
+        error: clean(last.error?.message ?? last.errors?.[0]?.message ?? '')
+      })
+    }
+  }
+  for (const child of suite.suites ?? []) collect(child, acc)
+  return acc
+}
+
+const render = report => {
+  const failures = (report.suites ?? []).flatMap(s => collect(s))
+  const { expected = 0, skipped = 0, flaky = 0 } = report.stats ?? {}
+  // Playwright reports a global-timeout abort as a top-level error.
+  const truncated = (report.errors ?? []).some(e =>
+    /^Timed out waiting .* for the/.test(clean(e.message))
+  )
+
+  const lines = [MARKER, '## Playwright on the preview', '']
+
+  if (!failures.length && !truncated) {
+    lines.push(`All tests passed. ${expected} passed, ${skipped} skipped.`)
+  } else {
+    lines.push(
+      `**${failures.length} failed**, ${expected} passed, ${skipped} skipped` +
+        (flaky ? `, ${flaky} flaky` : '') +
+        '.'
+    )
+  }
+
+  if (truncated) {
+    lines.push(
+      '',
+      '> The run hit its global timeout, so tests after the ones below never ran.'
+    )
+  }
+
+  for (const f of failures) {
+    lines.push('', `### \`${f.file}:${f.line}\` — ${f.title}`)
+    if (f.error) {
+      lines.push('', '```', truncate(f.error, 1200), '```')
+    }
+  }
+
+  lines.push('', '---', '')
+  if (PREVIEW_URL) lines.push(`Preview: ${PREVIEW_URL}  `)
+  if (RUN_URL) lines.push(`[Full run and HTML report](${RUN_URL})  `)
+  lines.push('Chrome only. Firefox and Edge run on Checkly against production.')
+
+  return lines.join('\n')
+}
+
+let report
+try {
+  report = JSON.parse(readFileSync(process.argv[2], 'utf8'))
+} catch {
+  // No JSON at all means Playwright died before writing one.
+  console.log(
+    [
+      MARKER,
+      '## Playwright on the preview',
+      '',
+      'The run produced no report. It most likely crashed or was cancelled ' +
+        'before any test finished.',
+      '',
+      RUN_URL ? `[Full run](${RUN_URL})` : ''
+    ].join('\n')
+  )
+  process.exit(0)
+}
+
+console.log(render(report))

package/templates/github/workflows/checkly-deploy.yml

@@ -0,0 +1,64 @@
+name: Deploy Checkly checks
+
+# Deploys the e2e suite as Checkly monitors when PRODUCTION deploys — not on
+# merge. Monitors must match what production serves: a merge that adds tests
+# for new data-testids goes red until the app deploy carrying those testids is
+# live, and with gated releases that gap can be days. `deployment_status`
+# fires when Vercel finishes the production deployment, so monitors update at
+# the exact moment the code they were recorded against is reachable.
+# `checkly deploy` is idempotent, so redeploying on every production deploy
+# is harmless.
+# Needs repo secrets: CHECKLY_API_KEY, CHECKLY_ACCOUNT_ID (1Password, "Checkly").
+on:
+  deployment_status:
+  workflow_dispatch:
+
+concurrency:
+  group: checkly-deploy
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.deployment_status.state == 'success' &&
+       github.event.deployment.environment == 'Production')
+    runs-on: ubuntu-latest
+    timeout-minutes: 8
+
+    steps:
+      - name: Check out the deployed ref
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.deployment.ref || github.ref }}
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          cache: pnpm
+
+      # --ignore-scripts: only the tests are bundled; project postinstall
+      # hooks are not needed and may want CMS tokens CI does not have.
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      # --force skips the interactive confirmation prompt.
+      - name: Deploy checks to Checkly
+        env:
+          CHECKLY_API_KEY: ${{ secrets.CHECKLY_API_KEY }}
+          CHECKLY_ACCOUNT_ID: ${{ secrets.CHECKLY_ACCOUNT_ID }}
+        run: pnpm exec checkly deploy --force
+
+      - name: Write result to job summary
+        if: always()
+        run: |
+          {
+            echo "## Checkly deploy"
+            echo ""
+            echo "- Ref: \`${{ github.event.deployment.ref || github.ref }}\`"
+            echo "- Triggered by a successful production deployment"
+          } >> "$GITHUB_STEP_SUMMARY"