From b0f24b27ebc832a0f136a0d21546c31c3bac6994 Mon Sep 17 00:00:00 2001 From: Matthew Connelly Date: Mon, 16 Nov 2026 18:35:17 -0500 Subject: [PATCH] fix(ci): release demos from trusted main pushes --- .github/workflows/superdoc-npm-release.yml | 20 +++---- README-analytics.md | 61 ++++++++++++++++++++++ README.md | 15 +++--- scripts/notify-superdoc-release.mjs | 9 +++- scripts/notify-superdoc-release.test.mjs | 49 ++++++++++++++--- 5 files changed, 127 insertions(+), 27 deletions(-) diff --git a/.github/workflows/superdoc-npm-release.yml b/.github/workflows/superdoc-npm-release.yml index 89c4208..bae47d6 100644 --- a/.github/workflows/superdoc-npm-release.yml +++ b/.github/workflows/superdoc-npm-release.yml @@ -3,10 +3,11 @@ name: SuperDoc npm release on: schedule: - cron: '17 0,8,16 * * *' - # Closed-and-merged only: use base-repository credentials even for fork PRs. - pull_request_target: - types: [closed] + # Release only committed base-repository code, including merged fork PRs. + push: branches: [main] + paths-ignore: + - '.github/superdoc-release.json' workflow_dispatch: inputs: dry_run: @@ -37,7 +38,6 @@ concurrency: jobs: check: - if: github.event_name != 'pull_request_target' || github.event.pull_request.merged == true runs-on: ubuntu-latest outputs: update: ${{ steps.check.outputs.update }} @@ -47,7 +47,7 @@ jobs: steps: - uses: actions/checkout@v6 with: - ref: ${{ github.event.pull_request.merge_commit_sha || github.sha }} + ref: ${{ github.sha }} - uses: actions/setup-node@v4 with: node-version: 22 @@ -57,7 +57,7 @@ jobs: id: check env: DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && (inputs.dry_run || inputs.simulated_latest != '' || inputs.simulated_deployed != '' || inputs.simulate_failure) && 'true' || 'false' }} - DEPLOY_CURRENT: ${{ github.event_name == 'pull_request_target' || inputs.deploy_current }} + DEPLOY_CURRENT: ${{ github.event_name == 'push' || inputs.deploy_current }} SIMULATED_LATEST: ${{ inputs.simulated_latest }} SIMULATED_DEPLOYED: ${{ inputs.simulated_deployed }} SIMULATE_FAILURE: ${{ inputs.simulate_failure }} @@ -91,7 +91,7 @@ jobs: with: environment: production dry_run: ${{ needs.check.outputs.dry_run == 'true' }} - ref: ${{ needs.update.outputs.commit_sha || github.event.pull_request.merge_commit_sha || github.sha }} + ref: ${{ needs.update.outputs.commit_sha || github.sha }} source_artifact: ${{ needs.update.outputs.source_artifact }} secrets: inherit @@ -108,7 +108,7 @@ jobs: - name: Record successful production deployment env: SUPERDOC_VERSION: ${{ needs.check.outputs.version }} - DEPLOYED_SOURCE_SHA: ${{ needs.update.outputs.commit_sha || github.event.pull_request.merge_commit_sha || github.sha }} + DEPLOYED_SOURCE_SHA: ${{ needs.update.outputs.commit_sha || github.sha }} run: | git fetch --depth=1 origin "$DEPLOYED_SOURCE_SHA" node scripts/record-superdoc-release.mjs @@ -122,13 +122,13 @@ jobs: notify: name: Notify Slack needs: [check, update, deploy, record] - if: ${{ always() && ((github.event_name == 'pull_request_target' && github.event.pull_request.merged == true) || github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && !inputs.dry_run && inputs.simulated_latest == '' && inputs.simulated_deployed == '' && !inputs.simulate_failure)) && (needs.check.result == 'failure' || needs.update.result == 'failure' || needs.deploy.result == 'failure' || needs.record.result == 'failure' || needs.check.result == 'cancelled' || needs.update.result == 'cancelled' || needs.deploy.result == 'cancelled' || needs.record.result == 'cancelled' || needs.deploy.result == 'success') }} + if: ${{ always() && (github.event_name == 'push' || github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && !inputs.dry_run && inputs.simulated_latest == '' && inputs.simulated_deployed == '' && !inputs.simulate_failure)) && (needs.check.result == 'failure' || needs.update.result == 'failure' || needs.deploy.result == 'failure' || needs.record.result == 'failure' || needs.check.result == 'cancelled' || needs.update.result == 'cancelled' || needs.deploy.result == 'cancelled' || needs.record.result == 'cancelled' || needs.deploy.result == 'success') }} runs-on: ubuntu-latest timeout-minutes: 5 steps: - uses: actions/checkout@v6 with: - ref: ${{ needs.update.outputs.commit_sha || github.event.pull_request.merge_commit_sha || github.sha }} + ref: ${{ needs.update.outputs.commit_sha || github.sha }} - uses: actions/setup-node@v4 with: node-version: 22 diff --git a/README-analytics.md b/README-analytics.md index 9cad49c..c890e4d 100644 --- a/README-analytics.md +++ b/README-analytics.md @@ -10,6 +10,67 @@ Readiness comes from the editor callback. Review, fields, agent jobs, Q&A and sa Release order: deploy homepage PR235 and verify its inert frame route first, then merge this gallery PR through the trusted maintainer workflow. The new transport has no historical baseline. +## Verify events after deployment + +Permanent console logs are not needed. Check each boundary separately: a browser +custom event, an outgoing Google request, then a received event in GA4. + +1. Open `https://demos.superdoc.dev/` without a query or fragment. Open DevTools, + select **Network**, enable **Preserve log**, and reload. Confirm + `/demo-analytics.js` returns JavaScript rather than the gallery HTML fallback. +2. Allow optional analytics through the gallery consent control. Wait for the + `www.superdoc.dev/demo-analytics-frame.html` frame and Google tag to load. + Declined consent, DNT/GPC, opt-out, private links and blocked Google requests + prevent collection; do not bypass those controls to make a check pass. +3. Filter Network by `collect` (all request types). Page activation should produce + `superdoc_demo_event` with `load_started` and, after about one visible second, + `exposed`. Click a demo card or source/docs link to check an actual user action. +4. Inspect the Google collection request's query parameters and body. Expected + fields include `tid=G-E4T80WRJGS`, `en=superdoc_demo_event`, + `ep.action`, `ep.example_id`, and the canonical `dl` page location. Requests can + be batched. A successful response proves transport, not final report ingestion. +5. In the existing GA4 property's **Realtime** report, look for + `superdoc_demo_event` under **Event count by event name**. Confirm the action + and demo parameters where available. Growth uses completed days and a refreshed + source observation, so it is not the immediate smoke-test surface. + +For an optional synthetic smoke test, run this once in the gallery page's console +after consent and frame initialization: + +```js +window.dispatchEvent(new CustomEvent('superdoc:demo', { + detail: { action: 'ai_started', capability: 'ai' } +})); +``` + +On the gallery homepage the resulting event has `example_id=gallery`, +`page_id=demo_gallery` and `page_location=https://demos.superdoc.dev/`. This records +real production activity if transport is enabled; prefer a real click for routine +checks. Repeating the same demo/action/capability on one page instance is +deduplicated. Reload before another smoke test. `dispatchEvent` returning `true` +does not prove that analytics accepted or sent the event. + +For temporary console inspection without changing production code, add a listener +that prints only the public categories: + +```js +const logDemoEvent = ({ detail }) => console.log('superdoc:demo', { + action: detail?.action, + capability: detail?.capability, + example: detail?.example ?? '(inferred from route)' +}); +window.addEventListener('superdoc:demo', logDemoEvent); +// When finished: +// window.removeEventListener('superdoc:demo', logDemoEvent); +``` + +That listener confirms the local dispatch only; automatically observed clicks +and exposures call the adapter directly and do not dispatch `superdoc:demo`. +Use Network and GA4 Realtime to verify those. Unknown actions and extra properties +are discarded. Adding `debug_mode` to `detail` does not enable GA4 DebugView. +For automated QA, use `node --test scripts/demo-analytics.test.mjs`: its transport +is mocked and does not send synthetic activity to production. + ## Every future published demo and example Josh's November 15 direction applies to every future demo and example, including public customer follow-ups and launches outside this gallery. Before readiness, record the stable resource ID, canonical public destination, developer task, meaningful action and expected result, native social/video metrics where relevant, reporting coverage and collection start date. Reuse the existing consented GA4 transport, Growth Analytics and weekly metrics publisher. diff --git a/README.md b/README.md index 49ce1f2..3d6b6a6 100644 --- a/README.md +++ b/README.md @@ -129,8 +129,9 @@ three times a day at 00:17, 08:17, and 16:17 UTC. A new stable version runs to production after the builds and tests pass. It uses the existing Cloudflare and Railway secrets; no token or change to the SuperDoc source repository is needed. GitHub schedules run from the default branch and may be delayed. -Merged pull requests into `main` also run this workflow to deploy the current -source, and manual runs remain available. +Pushes to `main`, including merged pull requests, also run this workflow to deploy +that exact source commit. Changes only to `.github/superdoc-release.json` do not +start another release. Manual runs remain available. `.github/superdoc-release.json` records the last successful automated deployment. The first scheduled run establishes that baseline by validating and deploying npm's @@ -198,11 +199,11 @@ The former `GOOGLE_CHAT_WEBHOOK_URL` and `SLACK_WEBHOOK_URL` secrets are not use Each message includes the SuperDoc version, failed stages when applicable, a workflow-log link, and all demo titles and production links from `demos.json`. Adding a demo to that catalog automatically includes it in future notifications. -Notifications are sent for merged PR deployments and stable release runs. -Post-merge releases use `pull_request_target` with `types: [closed]` and a merged-only -job guard, so fork PR merges retain repository deployment settings and secrets. -Only the merged base-repository commit is checked out; unmerged fork code is never -run in this privileged release workflow. +Notifications are sent for production source deployments from `main` and stable +release runs. Post-merge releases use the trusted `push` event and check out its +exact `github.sha` from the base repository. Fork PR code is validated separately +by the unprivileged `pull_request` workflow. Release notifications link the pushed +commit without assuming every push came from a PR. Routine checks with no release, PR updates, and manual dry runs or simulations stay silent. diff --git a/scripts/notify-superdoc-release.mjs b/scripts/notify-superdoc-release.mjs index d05d0cb..ce6df93 100644 --- a/scripts/notify-superdoc-release.mjs +++ b/scripts/notify-superdoc-release.mjs @@ -8,6 +8,10 @@ export function shouldNotifyTrigger({ env, event = {} }) { if (["pull_request", "pull_request_target"].includes(env.GITHUB_EVENT_NAME)) { return event.action === "closed" && event.pull_request?.merged === true; } + if (env.GITHUB_EVENT_NAME === "push") { + const defaultBranch = event.repository?.default_branch; + return Boolean(defaultBranch) && env.GITHUB_REF === `refs/heads/${defaultBranch}` && event.deleted !== true; + } if (env.GITHUB_EVENT_NAME === "schedule") return true; if (env.GITHUB_EVENT_NAME === "workflow_dispatch") { const inputs = event.inputs || {}; @@ -42,7 +46,8 @@ export function describeTrigger({ env, event = {} }) { const commit = event.after || env.GITHUB_SHA; const source = /^[a-f0-9]{40,64}$/i.test(commit || "") ? ` — <${repositoryUrl}/commit/${commit}|${commit.slice(0, 7)}>` : ""; - return `Branch testing after push or merge — ${label(env.GITHUB_REF_NAME || "unknown")}${source}`; + const kind = shouldNotifyTrigger({ env, event }) ? "Production source deployment — push to" : "Branch testing after push or merge —"; + return `${kind} ${label(env.GITHUB_REF_NAME || "unknown")}${source}`; } return `${label(env.GITHUB_EVENT_NAME || "Unknown trigger")} on ${label(env.GITHUB_REF_NAME || "unknown")}`; } @@ -116,7 +121,7 @@ export async function sendNotification({ botToken, channelId, message, fetchImpl export async function notifyRelease({ env = process.env, root = process.cwd(), fetchImpl = fetch } = {}) { const event = env.GITHUB_EVENT_PATH ? JSON.parse(await readFile(env.GITHUB_EVENT_PATH, "utf8")) : {}; if (!shouldNotifyTrigger({ env, event })) { - console.log("Notifications are limited to PR merges and stable releases."); + console.log("Notifications are limited to production deployments and stable release runs."); return; } const needs = JSON.parse(env.RELEASE_RESULTS); diff --git a/scripts/notify-superdoc-release.test.mjs b/scripts/notify-superdoc-release.test.mjs index 1ddd577..28fb140 100644 --- a/scripts/notify-superdoc-release.test.mjs +++ b/scripts/notify-superdoc-release.test.mjs @@ -51,7 +51,7 @@ test("PR titles and branch names cannot inject Slack markup or mentions", () => assert.ok(trigger.includes("&lt;!here&gt;")); }); -test("only merged PRs and stable release runs can notify", () => { +test("unmerged PRs, unrelated events and manual simulations cannot notify", () => { const env = { ...triggerEnv, GITHUB_EVENT_NAME: "pull_request_target" }; for (const action of ["opened", "synchronize", "reopened", "edited", "closed"]) { assert.equal(shouldNotifyTrigger({ env, event: { action, pull_request: { ...pullRequest, merged: false } } }), false); @@ -103,14 +103,47 @@ test("a merged fork PR in the trusted base context notifies with the original PR assert.match(payload.text, /codex\/full-reference-preset → main/); }); -test("the release workflow only grants the trusted merge context after a PR has merged", async () => { +test("the release workflow deploys exact main pushes without a privileged fork checkout", async () => { const workflow = await readFile(new URL("../.github/workflows/superdoc-npm-release.yml", import.meta.url), "utf8"); - assert.match(workflow, /^ pull_request_target:\n types: \[closed\]\n branches: \[main\]/m); - assert.doesNotMatch(workflow, /^ pull_request:/m); - assert.match(workflow, /if: github.event_name != 'pull_request_target' \|\| github.event.pull_request.merged == true/); - assert.match(workflow, /DEPLOY_CURRENT: \$\{\{ github.event_name == 'pull_request_target' \|\| inputs.deploy_current \}\}/); - assert.match(workflow, /github.event_name == 'pull_request_target' && github.event.pull_request.merged == true/); - assert.doesNotMatch(workflow, /pull_request\.head\.|refs\/pull\//); + assert.match(workflow, /^ push:\n branches: \[main\]\n paths-ignore:\n - '\.github\/superdoc-release\.json'/m); + assert.doesNotMatch(workflow, /pull_request_target|pull_request\.head\.|merge_commit_sha|refs\/pull\/|allow-unsafe-pr-checkout/); + assert.match(workflow, /DEPLOY_CURRENT: \$\{\{ github.event_name == 'push' \|\| inputs.deploy_current \}\}/); + assert.match(workflow, /ref: \$\{\{ github.sha \}\}/); + assert.match(workflow, /ref: \$\{\{ needs.update.outputs.commit_sha \|\| github.sha \}\}/); + assert.match(workflow, /github.event_name == 'push' \|\| github.event_name == 'schedule'/); + assert.match(workflow, /Live runs must use the default branch/); +}); + +test("only non-deletion pushes to the repository default branch can notify", () => { + const event = { repository: { default_branch: "main" }, deleted: false }; + const env = { ...triggerEnv, GITHUB_EVENT_NAME: "push", GITHUB_REF: "refs/heads/main" }; + assert.equal(shouldNotifyTrigger({ env, event }), true); + assert.equal(shouldNotifyTrigger({ env, event: { ...event, deleted: true } }), false); + assert.equal(shouldNotifyTrigger({ env, event: {} }), false); + for (const ref of ["refs/heads/feature", "refs/tags/main", "refs/pull/124/merge", undefined]) { + assert.equal(shouldNotifyTrigger({ env: { ...env, GITHUB_REF: ref }, event }), false); + } +}); + +test("a main push delivers a source deployment notification linked to the deployed commit", async (t) => { + const root = await mkdtemp(path.join(tmpdir(), "superdoc-main-push-")); + t.after(() => rm(root, { recursive: true, force: true })); + const commit = "b".repeat(40); + await writeFile(`${root}/demos.json`, JSON.stringify(demos)); + await writeFile(`${root}/event.json`, JSON.stringify({ after: commit, ref: "refs/heads/main", repository: { default_branch: "main" } })); + let payload; + await notifyRelease({ root, env: { + ...triggerEnv, GITHUB_EVENT_NAME: "push", GITHUB_REF: "refs/heads/main", GITHUB_EVENT_PATH: `${root}/event.json`, + GITHUB_RUN_ID: "123", GITHUB_RUN_ATTEMPT: "1", RELEASE_RESULTS: JSON.stringify(success), + SUPERDOC_VERSION: "2.31.0", RELEASE_DRY_RUN: "false", SLACK_BOT_TOKEN: botToken, SLACK_CHANNEL_ID: channelId, + }, fetchImpl: async (_url, request) => { + payload = JSON.parse(request.body); + return Response.json({ ok: true }); + } }); + assert.ok(payload); + assert.match(payload.text, /Trigger: Production source deployment — push to main/); + assert.ok(payload.text.includes(`https://github.com/superdoc/demos/commit/${commit}|bbbbbbb`)); + assert.doesNotMatch(payload.text, /PR merge|Branch testing/); }); test("successful deployments list every catalog demo with a production link", () => {