From b0769ed44b9344e6f615dccc7f267dfbd2d42611 Mon Sep 17 00:00:00 2001 From: Chris Barber Date: Fri, 28 Aug 2026 02:44:17 -0500 Subject: [PATCH 1/7] Point the docs regen at titaniumsdk.com The API docs move to tidev/titanium-www, so the dispatch retargets there and carries this repo's name in the payload. The old dispatch sent nothing, which is why the regen had to check out all 17 source repos to work out what had changed; it now fetches only this one. Fires on a push touching apidoc/ and on a published release, rather than only on a merged pull request, so a direct push to master is no longer missed. The dispatch step itself moves into a reusable workflow in titanium-www so the payload shape is defined once for all 17 source repos. Also drops two things carried along for years: a full-history checkout that a lint does not need, and an `if:` guarding npm ci on a `node-cache` step that does not exist in this file. --- .github/workflows/regen-docs.yml | 56 +++++++++++++++----------------- 1 file changed, 26 insertions(+), 30 deletions(-) diff --git a/.github/workflows/regen-docs.yml b/.github/workflows/regen-docs.yml index 7a3461c..a15d7ff 100644 --- a/.github/workflows/regen-docs.yml +++ b/.github/workflows/regen-docs.yml @@ -1,39 +1,35 @@ name: Regen Docs + +# Tells titaniumsdk.com to recompile this module's API docs. +# +# Fires on a change to apidoc/ and on a published release, rather than on every +# merged pull request, so a direct push to the default branch is not missed. on: - workflow_dispatch: - pull_request: - types: [ closed ] - branches: [ master ] - paths: [ 'apidoc/**' ] + push: + branches: [master] + paths: ['apidoc/**'] + release: + types: [published] jobs: - regen: - if: github.event.pull_request.merged == true || github.event_name == 'workflow_dispatch' + lint: runs-on: ubuntu-latest - name: Trigger Regen - + name: Lint steps: - - name: Checkout repository - uses: actions/checkout@v3 - with: - fetch-depth: 0 + - uses: actions/checkout@v6 - - name: Setup node - uses: actions/setup-node@v2 - with: - node-version: '16' - registry-url: 'https://registry.npmjs.org' + - uses: actions/setup-node@v4 + with: + node-version: '24' + cache: npm - - name: Install dependencies - run: npm ci - if: steps.node-cache.outputs.cache-hit != 'true' + - run: npm ci + - run: npm run lint:docs - - run: npm run lint:docs - name: Lint - - - name: Repository Dispatch - uses: peter-evans/repository-dispatch@v2 - with: - event-type: regen-api-docs - token: ${{ secrets.REGEN_DOCS_GITHUB_TOKEN }} - repository: tidev/titanium-docs + # The dispatch itself lives in titanium-www so the payload shape is defined + # once for all 17 source repos instead of copied into each. + notify: + needs: lint + uses: tidev/titanium-www/.github/workflows/notify-api-docs.yml@main + secrets: + dispatch-token: ${{ secrets.REGEN_DOCS_GITHUB_TOKEN }} From c95758f939a35b40f5982ab75b699affe77724ee Mon Sep 17 00:00:00 2001 From: Chris Barber Date: Fri, 28 Aug 2026 02:47:49 -0500 Subject: [PATCH 2/7] Keep the manual trigger and lint proposed changes Restores workflow_dispatch, which several of these repos had and the replacement dropped, removing the only way to force a regen by hand from the Actions tab. Adds a pull_request trigger so the lint job runs on a proposed change. Without it these PRs get no CI at all, and the Node bump from 16 to 24 would surface only after merge -- when a push to the default branch fails, the dispatch never fires, and nothing says so. notify is skipped on pull_request: a proposed change gets linted, not published. --- .github/workflows/regen-docs.yml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/workflows/regen-docs.yml b/.github/workflows/regen-docs.yml index a15d7ff..a44ac9f 100644 --- a/.github/workflows/regen-docs.yml +++ b/.github/workflows/regen-docs.yml @@ -3,8 +3,11 @@ name: Regen Docs # Tells titaniumsdk.com to recompile this module's API docs. # # Fires on a change to apidoc/ and on a published release, rather than on every -# merged pull request, so a direct push to the default branch is not missed. +# merged pull request, so a direct push to master is not missed. on: + workflow_dispatch: + pull_request: + paths: ['apidoc/**'] push: branches: [master] paths: ['apidoc/**'] @@ -28,8 +31,11 @@ jobs: # The dispatch itself lives in titanium-www so the payload shape is defined # once for all 17 source repos instead of copied into each. + # + # Skipped on pull_request: a proposed change gets linted, not published. notify: needs: lint + if: github.event_name != 'pull_request' uses: tidev/titanium-www/.github/workflows/notify-api-docs.yml@main secrets: dispatch-token: ${{ secrets.REGEN_DOCS_GITHUB_TOKEN }} From 5bd8a55973fe6ca1a3abae365d46d119ec46e7d5 Mon Sep 17 00:00:00 2001 From: Chris Barber Date: Fri, 28 Aug 2026 02:50:55 -0500 Subject: [PATCH 3/7] Do not let a lint failure block the docs regen notify no longer needs lint. Gating the dispatch on the lint job means an unrelated tooling problem stops the docs updating and nothing says so. ti.coremotion cannot run `npm ci` at all today -- its package-lock.json is out of sync with package.json, missing escape-string-regexp@1.0.5 -- so with the gate in place its docs would never regenerate again, silently. Its Regen Docs workflow has in fact never run once, and ti.map's last run failed in April. Genuinely malformed apidoc still cannot ship. The compile in titanium-www fails on unresolved references and schema violations and commits nothing, so the protection is downstream where it can see the whole corpus. The lint here is a second, advisory check and now reports independently. --- .github/workflows/regen-docs.yml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/workflows/regen-docs.yml b/.github/workflows/regen-docs.yml index a44ac9f..b4e65d0 100644 --- a/.github/workflows/regen-docs.yml +++ b/.github/workflows/regen-docs.yml @@ -32,9 +32,14 @@ jobs: # The dispatch itself lives in titanium-www so the payload shape is defined # once for all 17 source repos instead of copied into each. # + # Deliberately independent of the lint job. Gating the dispatch on it means an + # unrelated tooling problem stops the docs updating and nothing says so -- + # ti.coremotion cannot run `npm ci` at all today because its lockfile is out of + # sync with its package.json. Genuinely malformed apidoc still cannot ship: the + # compile in titanium-www fails on it and commits nothing. + # # Skipped on pull_request: a proposed change gets linted, not published. notify: - needs: lint if: github.event_name != 'pull_request' uses: tidev/titanium-www/.github/workflows/notify-api-docs.yml@main secrets: From 6a7fe00cc13567e941a93490187f8cc7ae6d9caf Mon Sep 17 00:00:00 2001 From: Chris Barber Date: Fri, 28 Aug 2026 03:00:34 -0500 Subject: [PATCH 4/7] Keep dispatching to titanium-docs as well Both pipelines now fire. The site currently being served keeps updating while the replacement is proven, and backing out is merging a revert rather than racing to restore a dispatch. The legacy job carries no payload because titanium-docs does not read one -- it rebuilds every source repo on any dispatch, which is the inefficiency titanium-www exists to replace. Marked for deletion once titaniumsdk.com is served from titanium-www. --- .github/workflows/regen-docs.yml | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/.github/workflows/regen-docs.yml b/.github/workflows/regen-docs.yml index b4e65d0..be4a11d 100644 --- a/.github/workflows/regen-docs.yml +++ b/.github/workflows/regen-docs.yml @@ -1,6 +1,6 @@ name: Regen Docs -# Tells titaniumsdk.com to recompile this module's API docs. +# Tells the docs sites to recompile this module's API docs. # # Fires on a change to apidoc/ and on a published release, rather than on every # merged pull request, so a direct push to master is not missed. @@ -29,8 +29,8 @@ jobs: - run: npm ci - run: npm run lint:docs - # The dispatch itself lives in titanium-www so the payload shape is defined - # once for all 17 source repos instead of copied into each. + # titaniumsdk.com. The dispatch lives in titanium-www so the payload shape is + # defined once for all 17 source repos instead of copied into each. # # Deliberately independent of the lint job. Gating the dispatch on it means an # unrelated tooling problem stops the docs updating and nothing says so -- @@ -44,3 +44,20 @@ jobs: uses: tidev/titanium-www/.github/workflows/notify-api-docs.yml@main secrets: dispatch-token: ${{ secrets.REGEN_DOCS_GITHUB_TOKEN }} + + # The old pipeline, kept running alongside the new one so the site currently + # being served stays current while the replacement is proven. It carries no + # payload because titanium-docs does not read one -- it rebuilds every source + # repo on any dispatch, which is the inefficiency titanium-www replaces. + # + # Delete this job once titaniumsdk.com is served from titanium-www (TI-52). + notify-legacy: + if: github.event_name != 'pull_request' + runs-on: ubuntu-latest + name: Notify titanium-docs (legacy) + steps: + - uses: peter-evans/repository-dispatch@v3 + with: + event-type: regen-api-docs + repository: tidev/titanium-docs + token: ${{ secrets.REGEN_DOCS_GITHUB_TOKEN }} From a944ac8af729eaafa733094f0583ea1444a22fee Mon Sep 17 00:00:00 2001 From: Chris Barber Date: Sat, 29 Aug 2026 13:17:06 -0500 Subject: [PATCH 5/7] Apply review feedback From the review on titanium-sdk#14564, applied to all 17 repos so the template stays identical across them: - Job renamed back to `regen`, matching what was there before. - actions/checkout and actions/setup-node moved to v7. - Node 26. - Every step given a name. The setup-node suggestion as written would have produced two steps -- a bare `- name:` followed by a separate `- uses:` -- so it is applied as one named step on v7. --- .github/workflows/regen-docs.yml | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/.github/workflows/regen-docs.yml b/.github/workflows/regen-docs.yml index be4a11d..b55c021 100644 --- a/.github/workflows/regen-docs.yml +++ b/.github/workflows/regen-docs.yml @@ -15,19 +15,24 @@ on: types: [published] jobs: - lint: + regen: runs-on: ubuntu-latest name: Lint steps: - - uses: actions/checkout@v6 + - name: Checkout repository + uses: actions/checkout@v7 - - uses: actions/setup-node@v4 + - name: Setup node + uses: actions/setup-node@v7 with: - node-version: '24' + node-version: '26' cache: npm - - run: npm ci - - run: npm run lint:docs + - name: Install dependencies + run: npm ci + + - name: Lint + run: npm run lint:docs # titaniumsdk.com. The dispatch lives in titanium-www so the payload shape is # defined once for all 17 source repos instead of copied into each. @@ -56,7 +61,8 @@ jobs: runs-on: ubuntu-latest name: Notify titanium-docs (legacy) steps: - - uses: peter-evans/repository-dispatch@v3 + - name: Repository dispatch + uses: peter-evans/repository-dispatch@v3 with: event-type: regen-api-docs repository: tidev/titanium-docs From f277a97f267235f285f398e704d7b29ae31e3576 Mon Sep 17 00:00:00 2001 From: Chris Barber Date: Sat, 29 Aug 2026 13:22:01 -0500 Subject: [PATCH 6/7] Use the latest repository-dispatch action peter-evans/repository-dispatch v3 -> v4, matching the version bumps applied across titanium-www's own workflows so every file in the pipeline pins the same majors. --- .github/workflows/regen-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/regen-docs.yml b/.github/workflows/regen-docs.yml index b55c021..22d80b0 100644 --- a/.github/workflows/regen-docs.yml +++ b/.github/workflows/regen-docs.yml @@ -62,7 +62,7 @@ jobs: name: Notify titanium-docs (legacy) steps: - name: Repository dispatch - uses: peter-evans/repository-dispatch@v3 + uses: peter-evans/repository-dispatch@v4 with: event-type: regen-api-docs repository: tidev/titanium-docs From 953cb8a557102500505ea55cd37a35d99dfaf2eb Mon Sep 17 00:00:00 2001 From: Chris Barber Date: Sat, 29 Aug 2026 23:28:24 -0500 Subject: [PATCH 7/7] Guard the dispatch jobs against forks, not the lint titanium-sdk carried `github.repository_owner == 'tidev'` and the module repos did not -- an inherited asymmetry, not a decision. Worse, this branch had it on the wrong job: once notify stopped depending on lint, guarding lint stopped guarding anything. A fork would skip the one job that is useful there and still run both dispatch jobs, which fail because a fork holds no dispatch token. The guard now sits on the two jobs that reach outside the repo, in all 17 repos. Forks lint their own apidoc changes, which is worth having, and produce no failing dispatch runs. It is about noise, not security. A fork has no REGEN_DOCS_GITHUB_TOKEN, and even with one the payload names the fork, which is not on titanium-www's allowlist -- that allowlist is the actual boundary. --- .github/workflows/regen-docs.yml | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/.github/workflows/regen-docs.yml b/.github/workflows/regen-docs.yml index 22d80b0..f32e646 100644 --- a/.github/workflows/regen-docs.yml +++ b/.github/workflows/regen-docs.yml @@ -42,10 +42,12 @@ jobs: # ti.coremotion cannot run `npm ci` at all today because its lockfile is out of # sync with its package.json. Genuinely malformed apidoc still cannot ship: the # compile in titanium-www fails on it and commits nothing. - # - # Skipped on pull_request: a proposed change gets linted, not published. notify: - if: github.event_name != 'pull_request' + # Skipped on pull_request: a proposed change gets linted, not published. + # Skipped in forks: they hold no dispatch token, so this would only ever + # produce a failing run. The allowlist in titanium-www is the actual + # boundary -- a fork's payload names the fork, which is not on it. + if: github.event_name != 'pull_request' && github.repository_owner == 'tidev' uses: tidev/titanium-www/.github/workflows/notify-api-docs.yml@main secrets: dispatch-token: ${{ secrets.REGEN_DOCS_GITHUB_TOKEN }} @@ -57,7 +59,11 @@ jobs: # # Delete this job once titaniumsdk.com is served from titanium-www (TI-52). notify-legacy: - if: github.event_name != 'pull_request' + # Skipped on pull_request: a proposed change gets linted, not published. + # Skipped in forks: they hold no dispatch token, so this would only ever + # produce a failing run. The allowlist in titanium-www is the actual + # boundary -- a fork's payload names the fork, which is not on it. + if: github.event_name != 'pull_request' && github.repository_owner == 'tidev' runs-on: ubuntu-latest name: Notify titanium-docs (legacy) steps: