ci: validate site builds on pull requests

[Shayne Boyer (spboyer)]

Closes #473

Summary

Adds .github/workflows/site-ci.yml — a PR-time validation workflow for the Starlight docs site that runs cd site && npm ci && npm run build so broken site changes are caught before merge instead of after.

Design

The workflow is triggered on every pull_request targeting main, so it can safely be marked as a required status check without deadlocking non-site PRs. Inside the single build job:

1. dorny/paths-filter@v3 checks whether any of these paths changed:
   • site/** (source, package.json, package-lock.json, config, content, e2e)
   • .github/workflows/site-ci.yml
   • .github/workflows/pages.yml
2. If yes → set up Node 22.12.0 (mirrors pages.yml), npm ci, npm run build.
3. If no → skip the build step and emit a fast success ("No site/** changes detected — skipping site build.").

The workflow also runs on push to main with the same path filter, so main-branch trend validation stays covered.

Why this shape

• Required-check safe. The single job always reports a conclusion on every PR, so branch protection can require Site Build / Build site without stalling PRs that don't touch the site.
• Fast for non-site PRs. Only checkout + a tiny filter action run when nothing under site/** changed. No Node setup, no npm ci.
• Mirrors existing patterns. Node version, cache setup, and build commands match the deploy workflow (.github/workflows/pages.yml), so nothing drifts between the PR check and the deploy path.
• Deploy path untouched. pages.yml still owns the actual GitHub Pages deploy on push to main.

Acceptance criteria mapping

• ✅ PRs touching site/** (including site/package-lock.json), site-ci.yml, or pages.yml build the docs site before merge.
• ✅ Non-site PRs still get a successful Site Build / Build site check (fast skip), so it can be added to required checks without deadlock.
• ✅ Dependabot PRs under site/** will now get the same PR-time build signal that pages.yml currently only provides after merge.

Follow-ups (out of scope, noted in issue)

• Optionally wire the site Playwright e2e job into this workflow (issue ci: validate site builds on pull requests #473 lists it as an optional follow-up).
• Add Site Build / Build site to branch-protection required checks (requires repo-admin action).

[Copilot]

Pull request overview

This PR adds a dedicated CI workflow to validate the Starlight documentation site (site/) on pull requests (and on pushes to main), enabling a required-check-safe “always reports” site build signal.

Changes:

• Added .github/workflows/site-ci.yml to run npm ci + npm run build for the docs site when relevant files change.
• Implemented a path filter so non-site PRs skip the expensive Node install/build while still producing a successful check.

Show a summary per file

File	Description
.github/workflows/site-ci.yml	New PR-time site build workflow with path-based skip logic to support required status checks

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Low

[Copilot]

Review details

Suppressed comments (3)

.github/workflows/site-ci.yml:40

• On push events, dorny/paths-filter typically relies on git diff between the before and after SHAs. With the default actions/checkout shallow fetch, the before commit often isn’t present, which can make the filter step fail and break the workflow run (even though the filter output isn’t needed on push because later steps already run when github.event_name == 'push'). Consider adding if: github.event_name == 'pull_request' to the Detect site changes step (simplest), or alternatively increase checkout fetch-depth so the diff is always available.

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

      - name: Detect site changes
        id: filter
        uses: dorny/paths-filter@0e4a8c6effa4802afeda77dc8d303f8176d7dfad # v3

.github/workflows/site-ci.yml:36

• The inline version comments (# v7.0.1, # v7.0.0) are easy to let drift from the pinned SHAs and can be misleading during audits/upgrades. Consider updating them to the exact release/tag that the SHA corresponds to (or removing the version comment and relying on the SHA + Dependabot metadata) to keep the workflow self-consistent.

        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

.github/workflows/site-ci.yml:50

• The inline version comments (# v7.0.1, # v7.0.0) are easy to let drift from the pinned SHAs and can be misleading during audits/upgrades. Consider updating them to the exact release/tag that the SHA corresponds to (or removing the version comment and relying on the SHA + Dependabot metadata) to keep the workflow self-consistent.

        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

Review details

Suppressed comments (3)

.github/workflows/site-ci.yml:33

• ubuntu-latest can change over time and introduce unexpected build failures when GitHub advances the default runner image. Consider pinning to a specific runner version (e.g., ubuntu-24.04)—ideally matching whatever .github/workflows/pages.yml uses—to keep PR validation consistent with deploy behavior.

    runs-on: ubuntu-latest

.github/workflows/site-ci.yml:36

• The workflow pins actions by commit SHA (good), but the inline version comments (# v7.0.1, # v7.0.0) need to be accurate to avoid confusion during future upgrades/audits. Recommend verifying these SHAs correspond to the stated release tags (or updating the comments to the correct tag) so the annotations remain trustworthy.

        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

.github/workflows/site-ci.yml:50

• The workflow pins actions by commit SHA (good), but the inline version comments (# v7.0.1, # v7.0.0) need to be accurate to avoid confusion during future upgrades/audits. Recommend verifying these SHAs correspond to the stated release tags (or updating the comments to the correct tag) so the annotations remain trustworthy.

        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite