Documentation Site - Staging Previews

[s2t2]

Right now when someone submits a PR that contains updated docstrings or changes to the documentation site, we need to pull down the code and run the documentation site locally to preview the changes.

However it would be nice to implement an automated workflow whereby on each PR we are able to view the updated documentation site on a PR-specific staging server.

Alternatively, if having separate PR-specific servers isn't feasible or practical, we can have a repo maintainer manually run a command to deploy the documentation site from a given branch to a single staging preview server. This should be fine because most often we would only be concerned with previewing one PR at a time.

[s2t2]

Chat gpt says...

Nice—MkDocs + mkdocstrings is a great setup. Since PRs come from forks, you’ll want a workflow that can (1) build untrusted code safely and (2) still push a preview somewhere you control. Here are two solid approaches; the first keeps GitHub Pages, the second offloads previews to a host that sandboxes builds.

Option 1 — Keep GitHub Pages with hardened PR previews (works with forks)

How it works

Use a pull_request_target workflow so the job runs with your repo’s permissions, then check out the PR’s HEAD commit explicitly (not the PR’s workflow files), build the docs, and deploy to gh-pages/pr-/. Lock down the token to least privileges, and don’t persist credentials to the checkout. (This pattern is recommended because forked PRs don’t get a writeable GITHUB_TOKEN with the normal pull_request event.)

MkDocs generates relative links by default, so serving from a subfolder like /pr-123/ generally “just works” unless you’ve hard-coded absolute /... links.

.github/workflows/pr-preview.yml

name: PR Preview (MkDocs)
on:
  pull_request_target:
    types: [opened, synchronize, reopened, closed]

permissions:
  contents: write        # push to gh-pages
  pull-requests: write   # comment preview URL
  actions: read

jobs:
  build-and-deploy:
    if: github.event.action != 'closed'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout PR HEAD safely
        uses: actions/checkout@v4
        with:
          # Check out the contributor’s commit without bringing in their workflow files
          repository: ${{ github.event.pull_request.head.repo.full_name }}
          ref: ${{ github.event.pull_request.head.sha }}
          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Cache pip
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }}
          restore-keys: ${{ runner.os }}-pip-

      - name: Install docs deps
        run: |
          python -m pip install --upgrade pip
          # adjust to your deps; mkdocstrings + handlers for python:
          pip install mkdocs mkdocstrings[python] mkdocs-material

      - name: Build docs
        run: mkdocs build --site-dir site

      - name: Deploy to gh-pages/pr-<num>
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          branch: gh-pages
          folder: site
          target-folder: pr-${{ github.event.number }}
          clean: false

      - name: Comment preview URL
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          message: |
            🧪 Preview ready:
            https://<YOUR-USER>.github.io/<YOUR-REPO>/pr-${{ github.event.number }}/

  cleanup:
    if: github.event.action == 'closed'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout gh-pages
        uses: actions/checkout@v4
        with:
          ref: gh-pages
          persist-credentials: false
      - name: Remove folder and push
        run: |
          git rm -r "pr-${{ github.event.number }}" || true
          git commit -m "Remove preview for PR #${{ github.event.number }}" || true
          git push

Notes & safety:

We use pull_request_target so we can push to gh-pages, but we only check out the PR’s code—not its workflow files—and we keep permissions minimal. Don’t run extra scripts from the PR beyond your MkDocs build. GitHub and security researchers specifically warn against running untrusted PR content with elevated tokens; this layout avoids most pitfalls.

If you deploy with a Pages workflow or a different deploy action, this still works; the JamesIves/github-pages-deploy-action supports deploying into a subfolder via target-folder.

Make sure your repo’s Pages is configured to publish from the gh-pages branch (Settings → Pages).

Option 2 — Use Cloudflare Pages or similar for previews (easiest with forks)

Platforms like Cloudflare Pages run builds in their own infra and give you a unique URL per PR automatically—no push-back to your repo necessary. This is the safest/lowest-maintenance route for forked PRs, and you can keep production on GitHub Pages if you want. (Cloudflare/Vercel/Netlify docs cover automatic PR preview deployments.)

---

MkDocs/mkdocstrings specifics

mkdocstrings (Python handler) parses code using Griffe rather than importing modules at runtime, which is good for safety. Still, treat PR builds as untrusted—avoid any custom build steps that execute arbitrary contributor code. (General security guidance around pull_request_target applies.)

If you have any absolute links like /assets/..., switch them to relative paths so previews under /pr-123/ don’t break. MkDocs’ docs call out that absolute paths aren’t adjusted.