fix(ci): add actions/checkout to docs preview + split build into two jobs

Without checkout the preview job cannot resolve the ./.github/actions/setup-pnpm-node
composite. Sparse-checkout fetches only the composite + .node-version so the runner
does not download the full repo for a Surge deploy. Splitting the matrix into
build-preview / build-production avoids spinning a runner on the idle flavor.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: FelixTJDietrich

.github/workflows/cd-docs.yml

@@ -31,91 +31,83 @@ permissions:
   statuses: write
 
 jobs:
-  build:
-    name: Build (${{ matrix.flavor }})
+  # build-preview and build-production are split so each only spins up a runner
+  # for the event it serves; collapsing into a matrix would burn ~30s on the
+  # idle flavor for every trigger. The shared steps live in setup-pnpm-node.
+  build-preview:
+    name: Build (preview)
+    if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - flavor: preview
-            condition: pull_request
-            base_url: "/"
-          - flavor: production
-            condition: push
-            base_url: "/Hephaestus/"
     steps:
-      - name: Gate by event
-        id: gate
-        run: |
-          if [[ "${{ matrix.condition }}" == "pull_request" && "${{ github.event_name }}" != "pull_request" ]]; then
-            echo "run=false" >> "$GITHUB_OUTPUT"
-          elif [[ "${{ matrix.condition }}" == "push" && ! ( "${{ github.event_name }}" == "push" && "${{ github.ref }}" == "refs/heads/main" ) ]]; then
-            echo "run=false" >> "$GITHUB_OUTPUT"
-          else
-            echo "run=true" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Checkout repository
-        if: steps.gate.outputs.run == 'true'
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-
-      - name: Setup pnpm + Node.js
-        if: steps.gate.outputs.run == 'true'
-        uses: ./.github/actions/setup-pnpm-node
-
-      - name: Cache Docusaurus build
-        if: steps.gate.outputs.run == 'true'
-        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: ./.github/actions/setup-pnpm-node
+      - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: |
             docs/.docusaurus
             docs/node_modules/.cache
-          key: ${{ runner.os }}-docusaurus-${{ matrix.flavor }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('docs/**/*.md', 'docs/**/*.mdx', 'docs/**/*.ts') }}
+          key: ${{ runner.os }}-docusaurus-preview-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('docs/**/*.md', 'docs/**/*.mdx', 'docs/**/*.ts') }}
           restore-keys: |
-            ${{ runner.os }}-docusaurus-${{ matrix.flavor }}-${{ hashFiles('pnpm-lock.yaml') }}-
-            ${{ runner.os }}-docusaurus-${{ matrix.flavor }}-
-
-      - name: Install dependencies
-        if: steps.gate.outputs.run == 'true'
-        run: pnpm install --frozen-lockfile
-
-      - name: Build documentation
-        if: steps.gate.outputs.run == 'true'
-        run: pnpm --filter docs run build
+            ${{ runner.os }}-docusaurus-preview-${{ hashFiles('pnpm-lock.yaml') }}-
+            ${{ runner.os }}-docusaurus-preview-
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm --filter docs run build
         env:
-          DOCUSAURUS_BASE_URL: ${{ matrix.base_url }}
+          DOCUSAURUS_BASE_URL: "/"
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: docs-build-preview
+          path: docs/build
+          retention-days: 1
 
-      - name: Upload build artifact
-        if: steps.gate.outputs.run == 'true'
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+  build-production:
+    name: Build (production)
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: ./.github/actions/setup-pnpm-node
+      - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
-          name: docs-build-${{ matrix.flavor }}
+          path: |
+            docs/.docusaurus
+            docs/node_modules/.cache
+          key: ${{ runner.os }}-docusaurus-production-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('docs/**/*.md', 'docs/**/*.mdx', 'docs/**/*.ts') }}
+          restore-keys: |
+            ${{ runner.os }}-docusaurus-production-${{ hashFiles('pnpm-lock.yaml') }}-
+            ${{ runner.os }}-docusaurus-production-
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm --filter docs run build
+        env:
+          DOCUSAURUS_BASE_URL: "/Hephaestus/"
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: docs-build-production
           path: docs/build
           retention-days: 1
 
   preview:
     name: PR Preview
-    needs: build
+    needs: build-preview
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     env:
       PREVIEW_URL: ls1intum-hephaestus-docs-pr-${{ github.event.number }}.surge.sh
     steps:
-      - name: Download build artifact
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          sparse-checkout: |
+            .github/actions/setup-pnpm-node
+            .node-version
+          sparse-checkout-cone-mode: false
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           name: docs-build-preview
           path: docs-build
-
-      - name: Setup pnpm + Node.js
-        uses: ./.github/actions/setup-pnpm-node
-
+      - uses: ./.github/actions/setup-pnpm-node
       - name: Deploy to Surge.sh
         run: pnpm dlx surge ./docs-build ${{ env.PREVIEW_URL }} --token ${{ secrets.SURGE_TOKEN }}
-
-      - name: Comment on PR
-        uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2
+      - uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2
         with:
           header: docs-preview
           message: |
@@ -126,9 +118,7 @@ jobs:
             🔗 **[View Docs Preview](https://${{ env.PREVIEW_URL }})**
 
             <sub>Preview for commit ${{ github.event.pull_request.head.sha }}. Updates automatically on new commits.</sub>
-
-      - name: Create Docs Preview status check
-        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+      - uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
         with:
           script: |
             const sha = context.payload.pull_request?.head?.sha || context.sha;
@@ -144,24 +134,19 @@ jobs:
 
   deploy:
     name: GitHub Pages
-    needs: build
+    needs: build-production
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
-      - name: Download build artifact
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           name: docs-build-production
           path: docs-build
-
-      - name: Upload to GitHub Pages
-        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
+      - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
         with:
           path: docs-build
-
-      - name: Deploy to GitHub Pages
-        id: deployment
+      - id: deployment
         uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4