From 0fbf9e5e9b42d5f608834f7af10aca2472bbb1cd Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Mon, 22 Dec 2025 16:30:26 -0500 Subject: [PATCH 1/2] fix(ci): complete PR preview path offset and fork PR handling (#6667) * fix(ci): add path offset for PR preview subdirectory baseURL When PR preview builds use a subdirectory baseURL like /docs-v2/pr-preview/pr-XXXX/, shortcodes that parse .RelPermalink to detect product context fail because the path has extra segments. This fix: - Adds config/pr-preview/params.yml with prPreviewPathOffset: 3 - Updates workflow to use -e pr-preview environment - Updates api-endpoint, influxdb/host, and children shortcodes to use the offset when indexing path segments - Adds nil-safety with default fallback for placeholder_host Normal builds are unaffected (offset defaults to 0). * fix(ci): add path offset to product-name and sidebar for PR previews Apply the same prPreviewPathOffset fix to product-name.html and sidebar.html that was applied in the initial PR #6665. These templates parse RelPermalink to detect product context, but when baseURL includes a subdirectory path (e.g., /docs-v2/pr-preview/pr-XXXX/), the path indices shift. This fix uses the configurable offset to skip extra path segments in PR preview builds. * fix(ci): skip PR preview for fork PRs and add notice comment Fork PRs cannot deploy to gh-pages because GITHUB_TOKEN has read-only access to the base repository. This is a GitHub security feature. Changes: - Add condition to skip preview job for fork PRs - Add fork-notice job to post helpful comment explaining limitation - Include local preview instructions for contributors --- .github/workflows/pr-preview.yml | 39 +++++++++++++++++++++++++--- layouts/partials/sidebar.html | 6 +++-- layouts/shortcodes/product-name.html | 4 ++- 3 files changed, 43 insertions(+), 6 deletions(-) diff --git a/.github/workflows/pr-preview.yml b/.github/workflows/pr-preview.yml index d0aba7ecc..0eb5d6b42 100644 --- a/.github/workflows/pr-preview.yml +++ b/.github/workflows/pr-preview.yml @@ -35,12 +35,45 @@ jobs: echo "should-run=true" >> $GITHUB_OUTPUT fi - # Build and deploy preview - preview: + # Notify fork PRs that preview is not available + fork-notice: needs: check-draft if: | needs.check-draft.outputs.should-run == 'true' && - github.event.action != 'closed' + github.event.action != 'closed' && + github.event.pull_request.head.repo.full_name != github.repository + runs-on: ubuntu-latest + steps: + - name: Post fork notice comment + uses: actions/github-script@v7 + with: + script: | + const { data: comments } = await github.rest.issues.listComments({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number + }); + + const marker = ''; + const existing = comments.find(c => c.body.includes(marker)); + + if (!existing) { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body: `${marker}\n## 📝 PR Preview Not Available\n\nPR previews are not available for pull requests from forks due to GitHub Actions security restrictions.\n\nTo preview your changes locally, run:\n\`\`\`bash\nnpx hugo server\n\`\`\`\n\nOnce merged, your changes will be visible on the production site.` + }); + } + + # Build and deploy preview + preview: + needs: check-draft + # Skip fork PRs - GITHUB_TOKEN doesn't have write access to push to gh-pages + if: | + needs.check-draft.outputs.should-run == 'true' && + github.event.action != 'closed' && + github.event.pull_request.head.repo.full_name == github.repository runs-on: ubuntu-latest steps: - name: Checkout diff --git a/layouts/partials/sidebar.html b/layouts/partials/sidebar.html index 0dd150396..85caa0d2f 100644 --- a/layouts/partials/sidebar.html +++ b/layouts/partials/sidebar.html @@ -1,8 +1,10 @@ {{ $currentPage := . }} {{ $productPathData := findRE "[^/]+.*?" .RelPermalink }} -{{ $product := index $productPathData 0 }} +{{/* Support deployments (such as CI tools) with subdirectory baseURL */}} +{{ $pathOffset := .Site.Params.prPreviewPathOffset | default 0 }} +{{ $product := index $productPathData (add $pathOffset 0) }} {{ $productName := (index .Site.Data.products $product).name }} -{{ $currentVersion := index $productPathData 1 }} +{{ $currentVersion := index $productPathData (add $pathOffset 1) }} {{ .Scratch.Set "menuKey" "menu"}} diff --git a/layouts/shortcodes/product-name.html b/layouts/shortcodes/product-name.html index 355ea5c25..d71e5bea6 100644 --- a/layouts/shortcodes/product-name.html +++ b/layouts/shortcodes/product-name.html @@ -1,5 +1,7 @@ {{- $productPathData := findRE "[^/]+.*?" .Page.RelPermalink -}} -{{- $currentProduct := index $productPathData 1 -}} +{{- /* Support deployments (such as CI tools) with subdirectory baseURL */ -}} +{{- $pathOffset := .Site.Params.prPreviewPathOffset | default 0 -}} +{{- $currentProduct := index $productPathData (add $pathOffset 1) -}} {{- $length := .Get 0 | default "long" -}} {{- $omit := .Get "omit" | default "" -}} {{- $scratch := newScratch -}} From 3bb92f3783241870153aad4b3f18a8b7da9a07c3 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Mon, 22 Dec 2025 16:56:40 -0500 Subject: [PATCH 2/2] ci(preview): Add PR Preview reference in DOCS-DEPLOYING.md (#6668) - Use pull request previews in GitHub for manual validation --- DOCS-DEPLOYING.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/DOCS-DEPLOYING.md b/DOCS-DEPLOYING.md index 7f3825dfb..b7e1097d0 100644 --- a/DOCS-DEPLOYING.md +++ b/DOCS-DEPLOYING.md @@ -221,6 +221,34 @@ The Cypress tests validate: See [DOCS-TESTING.md](DOCS-TESTING.md) for comprehensive testing documentation. +### PR Preview + +Generates previews for docs-v2 pull requests for manual validation in GitHub using the PR Preview Action. + +#### Workflow Files + +| File | Purpose | +| ---------------------------------------------- | ------------------------------------- | +| `.github/scripts/parse-pr-urls.js` | Extract docs URLs from PR description | +| `.github/scripts/detect-preview-pages.js` | Determine which pages to preview | +| `.github/scripts/prepare-preview-files.js` | Stage files for selective deployment | +| `.github/scripts/preview-comment.js` | Manage sticky PR comments | +| `.github/workflows/pr-preview.yml` | Main preview workflow | +| `.github/workflows/cleanup-stale-previews.yml` | Weekly orphan cleanup | +| `.github/PREVIEW_SETUP.md` | Setup documentation | + +#### Key Design Decisions + +1. **Selective deployment** - Only changed pages deployed (not full 529MB site) +2. **Reuse existing infrastructure** - Uses `content-utils.js` for change detection +3. **GitHub Pages** - Deploys to `gh-pages` branch under `pr-preview/pr-{number}/` +4. **Security hardening** - XSS protection, path traversal prevention, input validation +5. **50-page limit** - Prevents storage bloat on large PRs + +#### Related links + +- **Deploy PR Preview action:** + ## Troubleshooting ### s3deploy Not Found