ci: docs-build PR validation + cross-repo publish dispatch#1988
Draft
jeffredodd wants to merge 3 commits into
Draft
ci: docs-build PR validation + cross-repo publish dispatch#1988jeffredodd wants to merge 3 commits into
jeffredodd wants to merge 3 commits into
Conversation
Adds the release-snapshot + post-NPM-publish bits that pair with the Docusaurus site stood up in #1943: - ci.yaml: docs-build job validates the site compiles (onBrokenLinks / onBrokenAnchors: throw) at PR time rather than at release time. - prepare-release.yaml: snapshots docs for the released version via docusaurus docs:version and folds the snapshot into the release commit (idempotent so workflow reruns on the same release PR are safe). - publish-docs.yaml: fires on successful Publish to NPM; builds the site and pushes it to Gusto/embedded-sdk-docs gh-pages. Gated on the repo variable DOCS_PUBLISH_ENABLED so it lands dormant; activation runbook (GitHub App install, secrets, var, Pages enablement) is in the file header. - docusaurus.config.ts: points url at the obfuscated *.pages.github.io subdomain GitHub auto-assigns to internal repos as an interim home; swap to https://sdk.gusto.com when SDK-831 provisions the custom domain. - docs-site/versions.json + versioned_{docs,sidebars}/version-0.46.3: one-time bootstrap of the version dropdown at the currently released version. Subsequent releases self-snapshot via prepare-release.yaml. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The new docs-build / prepare-release / publish-docs workflows all run `npm ci` in docs-site/, which requires a committed lockfile. The site was stood up in #1943 with package-lock.json gitignored, so CI failed with EUSAGE on the first PR exercise of docs-build. Remove the gitignore line and commit the current lockfile. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reverses course on the SDK-owns-versioning approach in the prior commits of this PR. Versions and the public site now live in Gusto/embedded-sdk-docs; this repo is just the content producer. Why: snapshotting docs into this repo on every release would accrete a full copy of docs/ per version in git history, forever. The docs repo is the natural home for the version archive. - docs-site/versioned_docs, versioned_sidebars, versions.json: removed. Including the .gitkeep placeholders from #1943 — without versioning there's no reason for those directories to exist here at all. - docusaurus.config.ts: revert url to http://localhost and drop trailingSlash. The SDK-side docs-site is now strictly a local-dev preview of current docs; the public site (with its production URL and trailing-slash rules) lives in the docs repo. - prepare-release.yaml: drop the snapshot + amend steps. No docs snapshot in the release commit. - publish-docs.yaml: rewrite to fire a repository_dispatch event of type sdk-published on Gusto/embedded-sdk-docs with payload { version, sdk_ref }. The docs repo's workflow checks out the SDK at sdk_ref, ingests docs/, runs docusaurus docs:version $VERSION, builds, and publishes to Pages. The publish-docs job in this repo no longer builds or hosts anything — it's a thin trigger. Activation runbook updated: the publishing GitHub App now needs Contents:write on the docs repo (GitHub's required permission for repository_dispatch), not write access to gh-pages. The receiving workflow on the docs repo is a separate piece of work. The docs-build CI job and the docs-site/package-lock.json fix from earlier commits in this PR are unchanged — both are still useful for SDK-side validation of current docs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
jeffredodd
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Sets up the SDK side of a docs-publishing pipeline whose architecture is SDK = content producer, Gusto/embedded-sdk-docs = versioned site host. The docs repo owns the Docusaurus site, the version archive, and the Pages publish — this PR just adds CI validation and a thin trigger.
What lands
ci.yaml— newdocs-buildjob that runsnpm run docs:buildon every PR.docusaurus.config.tshasonBrokenLinks: 'throw'+onBrokenAnchors: 'throw', so broken links/anchors indocs/fail the PR check instead of breaking releases.docs-site/.gitignore+docs-site/package-lock.json— the lockfile was gitignored when the site was stood up in #1943. The new CI job runsnpm ciindocs-site/, which requires a committed lockfile. Track it.publish-docs.yaml(new) — fires on a successfulPublish to NPMworkflow run, mints a GitHub App token, and posts arepository_dispatchevent of typesdk-publishedatGusto/embedded-sdk-docswith payload{ version, sdk_ref }. The docs repo's workflow does the work: check out SDK atsdk_ref, ingestdocs/, rundocusaurus docs:version $VERSION, build, publish to Pages. Lands dormant behindvars.DOCS_PUBLISH_ENABLED == 'true'so no failed-check noise.What this PR does NOT do
versioned_docs/snapshots in this repo. Versions live in the docs repo.prepare-release.yamlsnapshot behavior. The release commit no longer carries a docs snapshot.publish-docs.yamlis a thin trigger only.repository_dispatchtypesdk-published) is a separate piece of work inGusto/embedded-sdk-docs.Activation runbook (separate, after merge)
Gusto/embedded-sdk-docswith Contents: write (GitHub's required permission forrepository_dispatch).DOCS_PUBLISH_APP_ID+DOCS_PUBLISH_APP_PRIVATE_KEYto this repo.Gusto/embedded-sdk-docsthat listens forrepository_dispatchtypesdk-published.DOCS_PUBLISH_ENABLED=trueto this repo.Test plan
docs-buildjob passes on this PR (proved by the prior pass ond5ec891a).publish-docs.yaml— its first real exercise will be the next NPM publish after activation. Until then it's gated off.workflow_dispatchPublish Docsonce to verify the App token + dispatch path end-to-end.History
PR went through one architectural change mid-review:
f5e7ad5dinitially landedversioned_docs/version-0.46.3/+ snapshot-on-release + static-output push to docs repogh-pages.4e2d5453reversed course: versions and publish belong in the docs repo, not here. This is the final architecture.🤖 Generated with Claude Code