[mdanish98]

What this does

Automates the one error-prone, mechanical step in maintaining the docs site: regenerating the bundled SSP files. After PR #692, whenever an SSP source YAML changes on github-pages, someone had to remember to run npm install && npm run bundle and commit exactly the right bundled-*.yaml files. Forgetting it brings back the Swagger UI resolver errors for v3.2+ specs.

This adds a GitHub Actions workflow (.github/workflows/bundle-specs.yml) that does it automatically.

Addresses #701.

How it works

• Trigger: a push to github-pages that changes a source V*_SSP-*.yaml, either shared openapi.yaml schema, or the bundling tooling.
• Action: npm ci → npm run bundle → commits only the regenerated */bundled-V*_SSP-*.yaml back to github-pages. If nothing changed, it commits nothing.
• Loop-safe: the path filter matches source/schema/tooling files but not generated bundled-V... files, so the bot's bundle-only commit never re-triggers this workflow.
• Pages deployment: requires a BUNDLE_PUSH_TOKEN secret (PAT or fine-grained token with Contents: write). Unlike GITHUB_TOKEN, a push made with this credential triggers the branch-based GitHub Pages rebuild. The token identity must also be allowed to push if github-pages is protected.

Verified locally: a full run bundles 34/34 SSPs and the output is byte-identical to the files currently committed.

What we deliberately did NOT automate — and why

We scoped this intentionally narrowly, because not everything here is safe to automate:

• Authoring/adding the SSP spec files on github-pages stays manual. The spec content on github-pages is hand-maintained and currently differs from main (the two branches have independently-authored v3.2 content). There is no reproducible transform from main, so a human must decide what lands.
• Switching the default version (DEFAULT_VERSION in versions.js and the default paths in the HTML viewers) stays manual — it's a deliberate one-off change per major/minor.
• No main → github-pages sync. Auto-copying specs from main would silently overwrite the hand-edited content on github-pages. That reconciliation (which branch is authoritative, and eventually making main the single source of truth) is a bigger architectural decision for the working group — out of scope here.

In short: bundling is deterministic and safe to automate; anything that authors spec content or changes the published version is not, so it stays under human control.

Docs

docs/README.md and docs/DEPLOYMENT-CHECKLIST.md are updated to spell out this automated-vs-manual split, keeping the local npm run bundle commands as a debug fallback.

For a later discussion (not in this PR)

• Reconcile the spec drift between main and github-pages.
• Consider making main the single source of truth and deploying the site via GitHub Actions (or a clean, CI-only Pages branch), which would let us stop committing bundled artifacts entirely.

[Copilot]

🟡 Changes recommended

Shared-schema triggers, Pages deployment with the default token, and default-branch registration for manual dispatch need correction.

3 open issues

• Schema-only changes skip bundle regeneration · New
• Manual workflow dispatch is unavailable from the default branch · New
• Regenerated bundles may not be published with GITHUB_TOKEN · New

What changed in this PR

Automates SSP bundling for the docs site while keeping specification authoring and version selection manual.

Changes:

• Adds a workflow to regenerate and commit bundled SSP files on github-pages.
• Documents automation, token setup, and local debugging commands.

File	Description
docs/​README.md	Explains automated bundling and manual responsibilities.
docs/​DEPLOYMENT-CHECKLIST.md	Updates maintenance steps for automation.
.github/​workflows/​bundle-specs.yml	Adds bundle regeneration and commit workflow.

_{Review effort: Balanced}

[mdanish98]

Good catch — fixed in 047caf8. The trigger now includes both Part1-MetaModel-Schemas/openapi.yaml and Part2-API-Schemas/openapi.yaml, since their definitions are inlined into every SSP bundle. The README and deployment checklist now mention these triggers as well.

[mdanish98]

Agreed — fixed in 047caf8. Since this workflow intentionally lives only on github-pages rather than the default branch, the advertised manual dispatch was not available. I removed workflow_dispatch and the Run workflow references from both docs; the documented local command remains the manual/debug fallback.

[mdanish98]

Agreed — fixed in 047caf8. BUNDLE_PUSH_TOKEN is now required rather than optional, with an early validation step and no GITHUB_TOKEN fallback. I also removed [skip ci] so the PAT push can trigger the branch-based Pages rebuild. The generated-file path does not match this workflow’s trigger, so it remains loop-safe. The token requirement and reason are now documented in both docs.

[mdanish98]

Pre-condition before merging

The repository or organization secret BUNDLE_PUSH_TOKEN is not configured yet and must be created before this PR is merged. The merge changes the workflow file on github-pages, so it will trigger the bundling workflow immediately. Without the secret, the workflow will stop at the token validation step and report a clear configuration error.

The token should be a PAT or fine-grained token with Contents: write access to this repository. If github-pages is protected, the token owner must also be allowed to bypass the relevant push restriction. A dedicated token is required instead of GITHUB_TOKEN so the generated bundle commit triggers the branch-based GitHub Pages rebuild.

@mjacoby would it be possible to configure BUNDLE_PUSH_TOKEN as defined above? We can also discuss this in our WG meeting.