pr-preview.yaml

name: Deploy PR Preview

on:
  pull_request_target:
    types: [opened, synchronize, reopened, closed]
    paths:
      - 'reference/**'
      - 'reference_versioned_docs/**'
      - 'reference_versioned_sidebars/**'
      - 'reference_versions.json'
      - 'docs/**'
      - 'fabric/**'
      - 'learn/**'
      - 'release-notes/**'
      - 'src/**'
      - 'static/**'
      - 'versioned_docs/**'
      - 'versioned_sidebars/**'
      - 'docusaurus.config.ts'
      - 'package-lock.json'
      - 'package.json'
      - 'historic-redirects.ts'
      - 'redirects.ts'
      - 'sidebars*.ts'
      - 'versions.json'

# Cancel previous runs when new commits are pushed to the PR
concurrency:
  group: pr-preview-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  deploy-preview:
    name: Deploy PR Preview
    runs-on: ubuntu-latest
    if: github.event.action != 'closed'
    environment: ${{ github.event.pull_request.head.repo.full_name != github.repository && 'preview' || null }}
    permissions:
      pull-requests: write
      deployments: write
      contents: read

    steps:
      - name: Checkout PR code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          # checkout v7 blocks fork-PR checkout under pull_request_target by
          # default. We opt in deliberately: fork PRs are gated behind the
          # 'preview' environment (see the job's `environment:` above), which
          # requires manual approval before secrets are exposed.
          allow-unsafe-pr-checkout: true

      - name: Setup Node.js
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: '24'
          cache: 'npm'
          cache-dependency-path: 'package-lock.json'

      - name: Install dependencies
        run: |
          echo "Installing dependencies..."
          npm ci

      - name: Build Docusaurus site
        env:
          DOCUSAURUS_BASE_URL: /pr-${{ github.event.pull_request.number }}
        run: |
          echo "Building site with base URL: $DOCUSAURUS_BASE_URL"
          npm run build

      - name: Upload build artifact for local testing
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: pr-${{ github.event.pull_request.number }}-build
          path: build/
          retention-days: 30

      - name: Prepare deployment directory
        run: |
          PR_DIR="pr-${{ github.event.pull_request.number }}"
          echo "Creating directory: $PR_DIR"
          mkdir -p "$PR_DIR"

          # Create config.yaml
          cat > "$PR_DIR/config.yaml" << 'EOF'
          static:
            files: 'build/**'
            urlPath: 'pr-${{ github.event.pull_request.number }}'
            extensions: ['html']
            index: true
          EOF

          # Copy build directory
          cp -r build "$PR_DIR/"

          echo "Contents of $PR_DIR:"
          ls -la "$PR_DIR"

      - name: Install Harper CLI
        run: |
          npm install -g harper

      - name: Deploy to HarperDB
        env:
          HARPER_PREVIEW_TARGET: ${{ secrets.HARPER_PREVIEW_TARGET }}
          HARPER_PREVIEW_USERNAME: ${{ secrets.HARPER_PREVIEW_USERNAME }}
          HARPER_PREVIEW_PASSWORD: ${{ secrets.HARPER_PREVIEW_PASSWORD }}
        run: |
          cd "pr-${{ github.event.pull_request.number }}"
          # Add your additional arguments here
          harper deploy \
            target=${HARPER_PREVIEW_TARGET}:9925 \
            username=$HARPER_PREVIEW_USERNAME \
            password=$HARPER_PREVIEW_PASSWORD \
            project=pr-${{ github.event.pull_request.number }} \
            restart=true \
            replicated=true

      - name: Create deployment
        env:
          HARPER_PREVIEW_TARGET: ${{ secrets.HARPER_PREVIEW_TARGET }}
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        with:
          script: |
            const prNumber = context.payload.pull_request.number;
            const target = process.env.HARPER_PREVIEW_TARGET;
            const deploymentUrl = `${target}/pr-${prNumber}`;

            // Create deployment
            const deployment = await github.rest.repos.createDeployment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              ref: context.payload.pull_request.head.sha,
              environment: `pr-${prNumber}`,
              description: `Preview deployment for PR #${prNumber}`,
              auto_merge: false,
              required_contexts: []
            });

            // Create deployment status
            await github.rest.repos.createDeploymentStatus({
              owner: context.repo.owner,
              repo: context.repo.repo,
              deployment_id: deployment.data.id,
              state: 'success',
              environment_url: deploymentUrl,
              description: 'Preview deployment successful'
            });

            // Also add a comment to the PR
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: prNumber,
              body: `## 🚀 Preview Deployment\n\nYour preview deployment is ready!\n\n🔗 **Preview URL:** ${deploymentUrl}\n\nThis preview will update automatically when you push new commits.`
            });

  cleanup-preview:
    name: Cleanup PR Preview
    runs-on: ubuntu-latest
    if: github.event.action == 'closed'
    permissions:
      pull-requests: write
      deployments: write
      contents: read

    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Setup Node.js
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: '24'
          cache: 'npm'
          cache-dependency-path: 'package-lock.json'

      - name: Install Harper CLI
        run: |
          npm install -g harper

      - name: Remove preview deployment
        env:
          HARPER_PREVIEW_TARGET: ${{ secrets.HARPER_PREVIEW_TARGET }}
          HARPER_PREVIEW_USERNAME: ${{ secrets.HARPER_PREVIEW_USERNAME }}
          HARPER_PREVIEW_PASSWORD: ${{ secrets.HARPER_PREVIEW_PASSWORD }}
        run: |
          # Add your cleanup command here (e.g., harper undeploy or similar)
          harper drop_component \
            target=${HARPER_PREVIEW_TARGET}:9925 \
            username=$HARPER_PREVIEW_USERNAME \
            password=$HARPER_PREVIEW_PASSWORD \
            project=pr-${{ github.event.pull_request.number }} \
            replicated=true \
            restart=true
          echo "Cleaning up preview for PR #${{ github.event.pull_request.number }}"

      - name: Update deployment status
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        with:
          script: |
            const prNumber = context.payload.pull_request.number;
            const environmentName = `pr-${prNumber}`;

            // Mark deployment as inactive
            const deployments = await github.rest.repos.listDeployments({
              owner: context.repo.owner,
              repo: context.repo.repo,
              environment: environmentName
            });

            for (const deployment of deployments.data) {
              await github.rest.repos.createDeploymentStatus({
                owner: context.repo.owner,
                repo: context.repo.repo,
                deployment_id: deployment.id,
                state: 'inactive',
                description: 'Preview deployment removed'
              });
            }

            // Add cleanup comment to PR
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: prNumber,
              body: `## 🧹 Preview Cleanup\n\nThe preview deployment for this PR has been removed.`
            });

      # Deleting an environment requires repository *administration* permission,
      # which can never be granted to the workflow's GITHUB_TOKEN (it is not an
      # available scope in the `permissions:` block). These steps mint an
      # installation token for an org-owned GitHub App that has
      # "Administration: read and write" on this repository. If the App isn't
      # configured (no PREVIEW_CLEANUP_APP_ID variable), both steps are skipped.
      - name: Generate environment-cleanup token
        id: cleanup-token
        if: ${{ vars.PREVIEW_CLEANUP_APP_ID != '' }}
        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
        with:
          app-id: ${{ vars.PREVIEW_CLEANUP_APP_ID }}
          private-key: ${{ secrets.PREVIEW_CLEANUP_APP_PRIVATE_KEY }}

      - name: Delete GitHub environment
        if: ${{ vars.PREVIEW_CLEANUP_APP_ID != '' }}
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        with:
          github-token: ${{ steps.cleanup-token.outputs.token }}
          script: |
            const environmentName = `pr-${context.payload.pull_request.number}`;

            await github.rest.repos.deleteAnEnvironment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              environment_name: environmentName
            });
            console.log(`Deleted environment: ${environmentName}`);