fix(ci): prevent gh-pages branch bloat (#6340)

.github/workflows/deploy-docs-and-extensions.yml

@@ -7,6 +7,10 @@ on:
     paths:
       - 'documentation/**'
 
+# Use same concurrency group as PR preview workflow to prevent race conditions
+# when both workflows try to modify gh-pages branch simultaneously
+concurrency: pr-preview
+
 jobs:
   deploy:
     runs-on: ubuntu-latest
@@ -40,10 +44,30 @@ jobs:
           npm install
           npm run build
 
+      - name: Checkout gh-pages branch
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        continue-on-error: true      # Branch may not exist on first deploy or in forks
+        uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # pin@v3
+        with:
+          ref: gh-pages
+          path: gh-pages-current
+
+      - name: Preserve pr-preview directory
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          # Copy pr-preview from current gh-pages to the new build (if it exists)
+          if [ -d "gh-pages-current/pr-preview" ]; then
+            cp -r gh-pages-current/pr-preview documentation/build/pr-preview
+            echo "Preserved pr-preview directory with $(ls gh-pages-current/pr-preview | wc -l) PR previews"
+          else
+            echo "No pr-preview directory to preserve"
+          fi
+
       - name: Deploy to /gh-pages
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         uses: peaceiris/actions-gh-pages@373f7f263a76c20808c831209c920827a82a2847 # pin@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: documentation/build
-          keep_files: true           # This preserves existing files in gh-pages branch especially for previews
+          keep_files: false          # Clean deploy - only keep what's in the build + pr-preview
+          force_orphan: true         # Create a fresh commit without history to prevent bloat