diff --git a/.github/doc-samples-guard.json b/.github/doc-samples-guard.json new file mode 100644 index 00000000..62539da1 --- /dev/null +++ b/.github/doc-samples-guard.json @@ -0,0 +1,4 @@ +{ + "_doc": "Providers whose doc-sourced samples are maintained in this repo rather than in hookdeck/webhook-registry samples-doc (see .github/scripts/guard-doc-samples.mjs).", + "upstream_owned": ["ordinal", "polytomic"] +} diff --git a/.github/scripts/guard-doc-samples.mjs b/.github/scripts/guard-doc-samples.mjs new file mode 100644 index 00000000..3b7ec79f --- /dev/null +++ b/.github/scripts/guard-doc-samples.mjs @@ -0,0 +1,53 @@ +// Doc-sourced samples (files with a `source` key) are edited in +// hookdeck/webhook-registry's samples-doc/ and arrive here through its sync +// workflow on the `registry-sync` branch. An edit made here directly is overwritten +// by the next sync, and between 2026-11-04 and 2026-11-19 edits made on either side +// left the hub and Inspect showing different events and values (#92-#94). +// +// This fails a pull request that adds, changes or deletes a doc-sourced file unless +// it comes from this repo's own `registry-sync` branch (a fork's branch of that name +// doesn't count). Captures (no `source` key) are unaffected. +// +// Replacing a doc sample with a capture is allowed, because a capture always wins, +// but only on a PR labelled `capture`: dropping the `source` key from a doc file and +// editing it would otherwise pass as a capture, and the sync would then leave it +// alone for good. +import { execFileSync } from "node:child_process"; +import { readFileSync } from "node:fs"; + +const base = process.argv[2]; +const headRef = process.env.HEAD_REF || ""; +const fromThisRepo = (process.env.HEAD_REPO || "") === (process.env.REPO || "-"); +const labelled = (process.env.PR_LABELS || "").split(",").includes("capture"); +const exempt = new Set(JSON.parse(readFileSync(".github/doc-samples-guard.json", "utf8")).upstream_owned); + +if (headRef === "registry-sync" && fromThisRepo) { + console.log("registry-sync branch: doc-sourced edits allowed."); + process.exit(0); +} + +const git = (...a) => execFileSync("git", a, { encoding: "utf8", maxBuffer: 1 << 28 }); +const read = (rev, path) => { + try { return JSON.parse(git("show", `${rev}:${path}`)); } catch { return null; } +}; +const isDoc = (d) => d !== null && typeof d === "object" && !Array.isArray(d) && "source" in d; + +const changed = git("diff", "--name-status", "--no-renames", `${base}...HEAD`) + .split("\n").filter(Boolean).map((l) => l.split("\t")); +const bad = []; +for (const [status, path] of changed) { + const m = path.match(/^providers\/([^/]+)\/[^/]+\/[^/]+\.json$/); + if (!m || exempt.has(m[1])) continue; + const before = read(base, path); + const after = status === "D" ? null : read("HEAD", path); + if (isDoc(after)) bad.push(`${status === "A" ? "adds" : "changes"} ${path}`); + else if (after === null && isDoc(before)) bad.push(`deletes ${path}`); + else if (isDoc(before) && !labelled) bad.push(`replaces doc sample ${path} with a capture (label the PR \`capture\` if it is one)`); +} +if (bad.length) { + console.log(`::error::This PR edits ${bad.length} doc-sourced sample(s). Make the change in hookdeck/webhook-registry samples-doc/; its sync workflow brings it here.`); + for (const b of bad.slice(0, 50)) console.log(` ${b}`); + if (bad.length > 50) console.log(` ... and ${bad.length - 50} more`); + process.exit(1); +} +console.log("No doc-sourced samples edited outside registry-sync."); diff --git a/.github/workflows/doc-samples-guard.yml b/.github/workflows/doc-samples-guard.yml new file mode 100644 index 00000000..0b5c43ab --- /dev/null +++ b/.github/workflows/doc-samples-guard.yml @@ -0,0 +1,25 @@ +name: Doc samples guard + +on: + pull_request: + types: [opened, synchronize, reopened, labeled, unlabeled] + paths: + - providers/** + +jobs: + guard: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: actions/setup-node@v4 + with: + node-version: 22 + - name: Doc-sourced samples come from webhook-registry + env: + HEAD_REF: ${{ github.head_ref }} + HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }} + REPO: ${{ github.repository }} + PR_LABELS: ${{ join(github.event.pull_request.labels.*.name, ',') }} + run: node .github/scripts/guard-doc-samples.mjs "origin/${{ github.base_ref }}" diff --git a/README.md b/README.md index 5e9c5330..c207675c 100644 --- a/README.md +++ b/README.md @@ -162,6 +162,16 @@ Two things follow from the marking: They come from [hookdeck/webhook-registry](https://github.com/hookdeck/webhook-registry) (`samples-doc/`), which records where each example was read and when. +**Edit them there, not here.** webhook-registry's `sync-samples` workflow mirrors +`samples-doc/` into this repo as a rolling pull request from the `registry-sync` +branch after every registry merge, and the *Doc samples guard* check fails any other +pull request that adds, changes or deletes a file with a `source` key. Captures are +never touched by the sync. A capture replacing a doc sample passes the guard on a pull +request labelled `capture`. +Personal data is scrubbed in the registry before export (its `verify.py` fails on +non-placeholder emails and public IPs). The few providers whose doc samples are +maintained here instead are listed in `.github/doc-samples-guard.json`. + ## Using the data The data is packaged into JSON files that are distributed over http. The files can be found on https://samples.hookdeck.com