ci: add Docs PR Preview workflow (build gate + per-PR preview)

[rajivml]

What

Adds a Docs PR Preview workflow (.github/workflows/docs-pr-preview.yml) that:

1. Builds the docs site on every PR touching docs/** or mkdocs.yml (full pipeline: npm ci → docs:api → mkdocs build). The build doubles as a CI gate — a broken docs change now fails a check instead of shipping on the next scheduled deploy.
2. Publishes a per-PR preview at https://uipath.github.io/uipath-typescript/pr-preview/pr-<N>/ for same-repo PRs, and tears it down when the PR closes — so reviewers can see rendered docs changes before merge.

Why

Today docs.yml only builds/deploys on a Monday schedule and manual dispatch, straight to production. Nothing validates or previews docs on a PR, so contributors can't see how a change will look and a broken build isn't caught until deploy. This closes that gap.

Security

• Uses pull_request (not pull_request_target) — fork PRs run with a read-only token and no secrets.
• The write-scoped preview deploy is gated to same-repo PRs; fork PRs still get the build gate.
• No untrusted event data (PR title/body/branch) is interpolated into any run: step — no command-injection surface.
• The one third-party action (rossjrw/pr-preview-action) is pinned to a full commit SHA.

One-time setup after merge

Repo Settings → Actions → General → Workflow permissions → Read and write (so the preview can publish to gh-pages). Pages already serves gh-pages, so no Pages change is needed.

Complements #602 (which adds the Template Gallery docs page).

🤖 Generated with Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-15 11:25 UTC

[claude]

Setting contents: write and pull-requests: write at workflow level means every build step — npm ci, npm run docs:api, mkdocs build — executes with repository write access. For same-repo PRs, a supply-chain compromise in an npm dependency could abuse this token.

The canonical hardening for pull_request workflows is to split into two jobs so the untrusted build code runs read-only:

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      # ... all build steps ...
      - uses: actions/upload-artifact@v4
        with:
          name: site
          path: site/

  deploy-preview:
    needs: build
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          name: site
          path: site/
      - uses: rossjrw/pr-preview-action@ffa7509e91a3ec8dfc2e5536c4d5c1acdf7a6de9
        with:
          source-dir: site
          preview-branch: gh-pages
          umbrella-dir: pr-preview
          action: auto

This way write credentials are never present in the process tree that runs untrusted build code. For fork PRs GitHub overrides the token to read-only anyway, so the real exposure is same-repo PRs only — but that's still worth minimising.

[claude]

docs/requirements.txt is already matched by the docs/** glob above it, so this entry is redundant.

Suggested change

- "docs/requirements.txt"

[claude]

Review summary

Two findings from this run:

1. Overly-broad workflow-level permissions (lines 28–30) — contents: write + pull-requests: write are granted at workflow level, so every build step (npm ci, docs:api, mkdocs build) runs with repository write access. Splitting into a read-only build job and a write-scoped deploy-preview job eliminates this exposure.

2. Redundant path filter entry (line 25) — docs/requirements.txt is already matched by docs/**; the explicit entry can be dropped.

[rajivml]

Folded into #602 — the Docs PR Preview workflow is now part of that PR so both changes review together.