docs-pr-preview.yml

name: Documentation (PR Preview)

# Use pull_request_target so the workflow has write permissions even for fork
# PRs. The pull_request trigger restricts fork PRs to a read-only GITHUB_TOKEN,
# which would prevent deploying to gh-pages and posting PR comments.
on:
  pull_request_target:
    types: [opened, synchronize, reopened]

env:
  SITE_DIR: /tmp/built-site

concurrency:
  group: docs-deploy
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    # Read-only permissions: ensures GITHUB_TOKEN has no write access when
    # running untrusted PR code.
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v6
        with:
          # Check out the PR head commit. Use the SHA (not a branch ref) to pin
          # to a specific, immutable commit.
          ref: ${{ github.event.pull_request.head.sha }}

      - uses: astral-sh/setup-uv@v7

      # Reference the action from @main so the build scripts (action.yml and
      # override_site_url.py) always come from the trusted main branch, not from
      # the PR's checkout.
      - uses: TaiSakuma/improved-octo-fortnight/.github/actions/build-docs@main
        id: build
        with:
          subdir: pr/${{ github.event.number }}
          site-dir: ${{ env.SITE_DIR }}

      - uses: actions/upload-artifact@v4
        with:
          name: docs-preview
          path: ${{ env.SITE_DIR }}
          retention-days: 1

  deploy:
    # This job never executes PR code. It only runs trusted code from main and
    # third-party actions.
    needs: build
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v6

      - uses: actions/download-artifact@v4
        with:
          name: docs-preview
          path: ${{ env.SITE_DIR }}

      # Reference the action from @main so deploy logic always comes from the
      # trusted main branch.
      - uses: TaiSakuma/improved-octo-fortnight/.github/actions/deploy-to-gh-pages@main
        id: deploy
        with:
          site-dir: ${{ env.SITE_DIR }}
          target: pr/${{ github.event.number }}
          commit-message: "Deploy PR #${{ github.event.number }} preview"

      - name: Post or update PR comment
        uses: actions/github-script@v7
        with:
          script: |
            const url = '${{ steps.deploy.outputs.url }}';

            // Wait for deployment to be live (poll every 10s, up to 5 min)
            let live = false;
            for (let i = 0; i < 30; i++) {
              try {
                const res = await fetch(url);
                if (res.ok) { live = true; break; }
              } catch (e) {}
              await new Promise(r => setTimeout(r, 10000));
            }

            const marker = '<!-- docs-preview -->';
            const status = live ? '' : '\n\n> **Note:** The preview may not be ready yet.';
            const body = `${marker}\n📖 Docs preview: ${url}${status}`;
            const { data: comments } = await github.rest.issues.listComments({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: ${{ github.event.number }},
            });
            const existing = comments.find(c => c.body.includes(marker));
            if (existing) {
              await github.rest.issues.updateComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                comment_id: existing.id,
                body,
              });
            } else {
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: ${{ github.event.number }},
                body,
              });
            }