Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions .github/workflows/superdoc-npm-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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 }}
Expand All @@ -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
Expand All @@ -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 }}
Expand Down Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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
Expand Down
61 changes: 61 additions & 0 deletions README-analytics.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
15 changes: 8 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand Down
9 changes: 7 additions & 2 deletions scripts/notify-superdoc-release.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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 || {};
Expand Down Expand Up @@ -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")}`;
}
Expand Down Expand Up @@ -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);
Expand Down
49 changes: 41 additions & 8 deletions scripts/notify-superdoc-release.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ test("PR titles and branch names cannot inject Slack markup or mentions", () =>
assert.ok(trigger.includes("&amp;lt;!here&amp;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);
Expand Down Expand Up @@ -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", () => {
Expand Down
Loading