cd-docs.yml

# Documentation Deployment Pipeline
#
# Separation of Concerns:
# - CI: Quality gate in ci-quality-gates.yml validates docs build
# - CD: This workflow handles deployment only (GitHub Pages + PR previews)
#
# Triggers:
# - push to main with docs changes: Deploy to GitHub Pages
# - PR with docs changes: Deploy preview to Surge.sh with comment
#
# Best Practices (2025):
# - Path filtering prevents unnecessary runs
# - Surge.sh teardown removes preview when PR closes
# - Uses upload-pages-artifact@v3 and deploy-pages@v4 per GitHub requirements
# - Docusaurus build caching for faster deploys

name: CD / Docs

on:
  push:
    branches: [main]
    paths:
      - "docs/**"
      - ".github/workflows/cd-docs.yml"
  # PR events for build/preview (path-filtered)
  pull_request:
    types: [opened, synchronize, reopened]
    paths:
      - "docs/**"
      - ".github/workflows/cd-docs.yml"
  workflow_dispatch:

# Separate workflow for teardown - see cd-docs-teardown.yml
# Path filters are unreliable for 'closed' events, so teardown is in a separate workflow

concurrency:
  group: docs-deploy-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || github.ref }}
  cancel-in-progress: true

permissions:
  contents: read
  pages: write
  id-token: write
  pull-requests: write
  statuses: write

jobs:
  # Build docs for PR preview (baseUrl = '/')
  build-preview:
    name: Build (Preview)
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4

      - name: Setup Node.js
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version-file: ".node-version"
          cache: npm
          cache-dependency-path: docs/package-lock.json

      - name: Cache Docusaurus build
        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
        with:
          path: |
            docs/.docusaurus
            docs/node_modules/.cache
          key: ${{ runner.os }}-docusaurus-preview-${{ hashFiles('docs/package-lock.json') }}-${{ hashFiles('docs/**/*.md', 'docs/**/*.mdx', 'docs/**/*.ts') }}
          restore-keys: |
            ${{ runner.os }}-docusaurus-preview-${{ hashFiles('docs/package-lock.json') }}-
            ${{ runner.os }}-docusaurus-preview-

      - name: Install dependencies
        run: npm ci --no-audit --progress=false
        working-directory: docs

      - name: Build documentation (preview)
        run: npm run build
        working-directory: docs
        env:
          DOCUSAURUS_BASE_URL: "/"

      - name: Upload build artifact
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: docs-build-preview
          path: docs/build
          retention-days: 1

  # Build docs for production (baseUrl = '/Hephaestus/')
  build-production:
    name: Build (Production)
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4

      - name: Setup Node.js
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version-file: ".node-version"
          cache: npm
          cache-dependency-path: docs/package-lock.json

      - name: Cache Docusaurus build
        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
        with:
          path: |
            docs/.docusaurus
            docs/node_modules/.cache
          key: ${{ runner.os }}-docusaurus-prod-${{ hashFiles('docs/package-lock.json') }}-${{ hashFiles('docs/**/*.md', 'docs/**/*.mdx', 'docs/**/*.ts') }}
          restore-keys: |
            ${{ runner.os }}-docusaurus-prod-${{ hashFiles('docs/package-lock.json') }}-
            ${{ runner.os }}-docusaurus-prod-

      - name: Install dependencies
        run: npm ci --no-audit --progress=false
        working-directory: docs

      - name: Build documentation (production)
        run: npm run build
        working-directory: docs

      - name: Upload build artifact
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: docs-build-production
          path: docs/build
          retention-days: 1

  # PR Preview: Deploy to Surge.sh with custom comment
  preview:
    name: PR Preview
    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
        with:
          name: docs-build-preview
          path: docs-build

      - name: Install Surge
        run: npm install -g surge

      - name: Deploy to Surge.sh
        run: surge ./docs-build ${{ env.PREVIEW_URL }} --token ${{ secrets.SURGE_TOKEN }}

      - name: Comment on PR
        uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2
        with:
          header: docs-preview
          message: |
            ## 📚 Documentation Preview

            This PR includes documentation changes. A preview has been deployed:

            🔗 **[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
        with:
          script: |
            const sha = context.payload.pull_request?.head?.sha || context.sha;
            await github.rest.repos.createCommitStatus({
              owner: context.repo.owner,
              repo: context.repo.repo,
              sha: sha,
              state: 'success',
              target_url: 'https://${{ env.PREVIEW_URL }}',
              description: 'Click Details to view Docs Preview',
              context: 'Preview / Docs'
            });

  # Teardown handled by cd-docs-teardown.yml (separate workflow for reliability)

  # Production: Deploy to GitHub Pages
  deploy:
    name: GitHub Pages
    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
        with:
          name: docs-build-production
          path: docs-build

      - name: Upload to GitHub Pages
        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
        with:
          path: docs-build

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4