ci: validate, build, and deploy Mintlify docs via OIDC

Add docs npm toolchain (mint export, Pagefind, llms.txt), combine validate
and S3/CloudFront deploy in docs.yml, and exclude docs workflows from the
main CI-CD path filter so doc-only changes do not trigger node builds.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: abs2023

.github/workflows/build.yml

@@ -41,7 +41,13 @@ on:
       - dev
       - cicd/*
 
-    paths: [".github/**", "ui-desktop/**", "ui-core/**", "proxy-router/**", "cli/**"]
+    paths:
+      - ".github/**"
+      - "!.github/workflows/docs.yml"
+      - "ui-desktop/**"
+      - "ui-core/**"
+      - "proxy-router/**"
+      - "cli/**"
 
   # pull_request:
   #   types: [opened, reopened, synchronize]

.github/workflows/docs.yml

@@ -1,5 +1,8 @@
 name: Docs
 
+# Validate Mintlify docs on PRs and pushes. Deploy to S3 + CloudFront (OIDC) on
+# test/main after validation passes. Does not trigger the main CI-CD pipeline.
+
 on:
   pull_request:
     paths:
@@ -17,6 +20,10 @@ on:
       - ".github/workflows/docs.yml"
   workflow_dispatch:
 
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
 permissions:
   contents: read
   pull-requests: write
@@ -33,16 +40,18 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: "20"
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
 
-      - name: Install Mintlify CLI
-        run: npm install -g mint@latest
+      - name: Install docs dependencies
+        working-directory: docs
+        run: npm ci
 
       - name: Validate Mintlify config
         working-directory: docs
         run: |
-          # Mintlify CLI command may evolve; we accept either name
-          mint --version
-          mint broken-links || echo "::warning::mint broken-links reported issues"
+          npx mint --version
+          npx mint broken-links || echo "::warning::mint broken-links reported issues"
 
       - name: List MDX files
         run: find docs -name "*.mdx" | wc -l
@@ -77,20 +86,17 @@ jobs:
       - name: Find pages with last_verified older than the latest release tag
         run: |
           set -euo pipefail
-          # Determine the latest non-test release tag, fall back to v0.0.0
           LATEST_TAG=$(git tag --list 'v*' --sort=-v:refname | grep -v -- '-test' | head -n 1 || true)
           LATEST_TAG=${LATEST_TAG:-v0.0.0}
           echo "Latest release tag: $LATEST_TAG"
 
           STALE_FILES=()
           while IFS= read -r f; do
-            # Read first 30 lines for frontmatter and grep last_verified
             VERIFIED=$(awk '/^---$/{n++; next} n==1 && /^last_verified:/ {print}' "$f" \
               | sed -E 's/^last_verified:[[:space:]]*"?([^"]*)"?$/\1/' || true)
             if [ -z "$VERIFIED" ]; then
               continue
             fi
-            # Compare lexicographically; vN.N.N strings sort correctly enough for warnings
             if [ "$VERIFIED" \< "$LATEST_TAG" ]; then
               STALE_FILES+=("$f (last_verified=$VERIFIED < $LATEST_TAG)")
             fi
@@ -104,3 +110,56 @@ jobs:
           else
             echo "All pages report last_verified >= $LATEST_TAG."
           fi
+
+  deploy:
+    name: Build and deploy docs
+    needs:
+      - mintlify-validate
+      - openapi-lint
+      - last-verified-staleness
+    if: github.event_name == 'push' && (github.ref_name == 'test' || github.ref_name == 'main')
+    runs-on: ubuntu-latest
+    environment: ${{ github.ref_name }}
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install docs dependencies
+        working-directory: docs
+        run: npm ci
+
+      - name: Build static site
+        working-directory: docs
+        env:
+          SITE_URL: ${{ vars.NODEDOCS_SITE_URL }}
+        run: npm run build:site -- ../.site
+
+      - name: Configure AWS credentials (OIDC)
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ vars.NODEDOCS_IAM_ROLE_ARN }}
+          aws-region: us-east-2
+
+      - name: Sync to S3
+        run: |
+          aws s3 sync .site/ "s3://${{ vars.NODEDOCS_S3_BUCKET }}/" \
+            --delete \
+            --exclude "serve.js" \
+            --exclude "Start Docs.command" \
+            --exclude "Start Docs.bat"
+
+      - name: Invalidate CloudFront
+        run: |
+          aws cloudfront create-invalidation \
+            --distribution-id "${{ vars.NODEDOCS_CLOUDFRONT_DISTRIBUTION_ID }}" \
+            --paths "/*"

.gitignore

@@ -4,4 +4,5 @@
 ***/.env
 ***/.$*drawio.bkp
 ***/.$*drawio.dtmp
-*.internal.*
+*.internal.*
+.site/

docs/.gitignore

@@ -2,3 +2,4 @@
 node_modules/
 .DS_Store
 *.log
+.site/