ci: docs-build PR validation + cross-repo publish dispatch

.github/workflows/ci.yaml

@@ -167,6 +167,26 @@ jobs:
       - name: Build Storybook
         run: npm run build-storybook
 
+  # Docs build job: validates the Docusaurus site compiles, catching broken
+  # links/anchors (onBrokenLinks: 'throw') at PR time rather than at release
+  # time. Uses its own node_modules under docs-site/ — not the root cache.
+  docs-build:
+    needs: setup
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install docs dependencies
+        working-directory: docs-site
+        run: npm ci
+
+      - name: Build docs
+        run: npm run docs:build
+
   # SDK app build job: validates the dev app's vite config and entry compile
   sdk-app-build:
     needs: setup

.github/workflows/publish-docs.yaml

@@ -0,0 +1,79 @@
+name: Publish Docs
+
+# Fires after a successful NPM publish on main and tells the docs repo
+# (Gusto/embedded-sdk-docs) to ingest the SDK's docs/ content at the
+# released SHA as a new version. Lives in its own workflow file so a
+# docs-publish failure does not fail the NPM publish, and vice versa.
+#
+# Architecture: this repo is the content producer. The docs repo owns the
+# Docusaurus site, the version archive, and the gh-pages publish. We
+# dispatch a `sdk-published` repository_dispatch event with the released
+# SHA, and the docs repo's workflow handles checkout + `docusaurus
+# docs:version` + build + Pages publish.
+#
+# Activation gate: the dispatch job is gated on the repo variable
+# DOCS_PUBLISH_ENABLED == 'true'. While that variable is unset, every
+# release skips this job cleanly (no failed-check noise). To turn the
+# pipeline on:
+#   1. Provision the cross-repo publishing GitHub App and install it on
+#      Gusto/embedded-sdk-docs with `contents: write` (GitHub requires
+#      Contents:write to trigger repository_dispatch).
+#   2. Add repo secrets DOCS_PUBLISH_APP_ID and DOCS_PUBLISH_APP_PRIVATE_KEY
+#      to Gusto/embedded-react-sdk.
+#   3. Add repo variable DOCS_PUBLISH_ENABLED=true.
+#   4. Implement the receiving workflow in Gusto/embedded-sdk-docs that
+#      listens for repository_dispatch type=sdk-published with payload
+#      { version, sdk_ref } and runs the snapshot + build + publish.
+
+on:
+  workflow_run:
+    workflows: [Publish to NPM]
+    types: [completed]
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: publish-docs
+  cancel-in-progress: false
+
+jobs:
+  dispatch:
+    # Dormant until DOCS_PUBLISH_ENABLED is set (see header). workflow_dispatch
+    # honors the same gate so manual triggers can't fire into missing secrets.
+    if: |
+      vars.DOCS_PUBLISH_ENABLED == 'true' &&
+      (github.event_name == 'workflow_dispatch' ||
+       github.event.workflow_run.conclusion == 'success')
+    runs-on:
+      group: gusto-ubuntu-default
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+
+      - name: Read released version
+        id: version
+        run: echo "version=$(node -p "require('./package.json').version")" >> "$GITHUB_OUTPUT"
+
+      - name: Mint GitHub App token for docs repo
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.DOCS_PUBLISH_APP_ID }}
+          private-key: ${{ secrets.DOCS_PUBLISH_APP_PRIVATE_KEY }}
+          owner: Gusto
+          repositories: embedded-sdk-docs
+
+      - name: Dispatch sdk-published event to docs repo
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          VERSION: ${{ steps.version.outputs.version }}
+          SDK_REF: ${{ github.event.workflow_run.head_sha || github.sha }}
+        run: |
+          jq -n \
+            --arg version "$VERSION" \
+            --arg sdk_ref "$SDK_REF" \
+            '{event_type: "sdk-published", client_payload: {version: $version, sdk_ref: $sdk_ref}}' \
+            | gh api repos/Gusto/embedded-sdk-docs/dispatches --input -

docs-site/.gitignore

@@ -2,4 +2,3 @@ node_modules/
 .docusaurus/
 build/
 .cache-loader/
-package-lock.json

docs-site/docusaurus.config.ts

@@ -7,6 +7,9 @@ const config: Config = {
   tagline: 'Embedded Payroll React SDK Documentation',
   favicon: 'img/favicon.svg',
 
+  // docs-site/ in this repo is a local-dev preview of the current docs
+  // only. The public site (with version history) lives in
+  // Gusto/embedded-sdk-docs and owns its own production URL.
   url: 'http://localhost',
   baseUrl: '/',