ci(docs): Add changed docs preview links

[betegon]

DESCRIBE YOUR PR

Adds a GitHub Actions workflow that listens for successful Vercel preview deployments, resolves the related PR, and posts one stable bot comment with direct preview links for changed docs pages.

The script uses the generated doctree source paths to map changed docs/ and develop-docs/ files to rendered preview URLs. Shared/common docs are grouped and capped so reviewers get useful links without an enormous comment. Include-only files are listed separately when they do not map directly to a public page.

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.

• Urgent deadline (GA date, etc.):
• Other deadline:
• None: Not urgent, can wait up to 1 week+

SLA

• Teamwork makes the dream work, so please add a reviewer to your PRs.
• Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it.
  Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

• Checked Vercel preview for correctness, including links
• PR was reviewed and approved by any necessary SMEs (subject matter experts)
• PR was reviewed and approved by a member of the Sentry docs team

Test Plan

• pnpm test scripts/docs-preview-links.spec.ts
• pnpm exec eslint scripts/docs-preview-links.ts scripts/docs-preview-links.spec.ts
• pnpm exec prettier --check scripts/docs-preview-links.ts scripts/docs-preview-links.spec.ts .github/workflows/docs-preview-links.yml
• pnpm exec tsc --noEmit --skipLibCheck --target ESNEXT --module commonjs --lib dom,esnext --types node --moduleResolution node --esModuleInterop scripts/docs-preview-links.ts

LEGAL BOILERPLATE

Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms.

EXTRA RESOURCES

• Sentry Docs contributor guide

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ready	Preview, Comment	Jun 15, 2026 4:38pm
sentry-docs	Ready	Preview, Comment	Jun 15, 2026 4:38pm

[sentry-warden]

Fork-controlled code executes with write-scoped GITHUB_TOKEN via deployment_status checkout

The deployment_status-triggered workflow checks out the deployed commit (a fork PR head when Vercel deploys fork PRs) with no ref pinning, then runs pnpm install --frozen-lockfile and a TypeScript script from that untrusted tree while holding a GITHUB_TOKEN with issues: write, letting a fork contributor run arbitrary code on the runner and post deceptive bot comments. Pin checkout to a trusted ref (e.g. the base SHA) and avoid running untrusted install hooks/scripts under a write-scoped token.

Evidence

• Trigger is deployment_status (a privileged trigger that runs in the base-repo context); the if only filters on deployment state/environment, not on trust of the source.
• actions/checkout at line 20 of .github/workflows/docs-preview-links.yml has no ref: override, so for deployment_status it checks out github.sha, the deployed commit — the fork PR head when Vercel deploys fork PRs.
• pnpm install --frozen-lockfile (line 30) runs against the fork-controlled tree; --frozen-lockfile does not disable preinstall/postinstall lifecycle scripts, so a malicious package.json executes arbitrary commands.
• pnpm exec tsx scripts/docs-preview-links.ts (line 32) then executes fork-controlled script source.
• The job token has issues: write, so attacker code can post/edit PR/issue comments as the bot; no broader secrets are present, bounding impact.

_{Identified by Warden security-review · 6D6-WYQ}

[sentry-warden]

PR-author doc frontmatter injected unsanitized into bot PR comment markdown (link spoofing)

renderPreviewComment interpolates PR-author-controlled frontmatter.title and node.path directly into the markdown link text/target of the github-actions bot comment without escaping, so a crafted title like foo](https://attacker.com) [x renders a spoofed link inside an otherwise-trusted bot comment to phish reviewers. Escape ], (, ) and backticks in title/path before interpolation.

Evidence

• Workflow docs-preview-links.yml runs scripts/docs-preview-links.ts on deployment_status success and posts a comment via issues: write.
• fetchDocTrees(previewUrl) loads doctree.json, whose frontmatter.title and path come from the PR author's .md/.mdx source.
• buildSourcePathIndex stores node.frontmatter?.title verbatim and normalizePagePath only trims slashes.
• renderPreviewComment emits - [${formatPageLabel(page)}](${page.url}) with formatPageLabel = ${page.title} - /${page.path}/, so ]/(/) in title breaks out of the link and injects an attacker-controlled markdown link.
• Impact is bounded: GitHub sanitizes markdown HTML (no script execution) and the PR author can already comment directly, so this is link/content spoofing in a bot comment rather than XSS or privileged action.

_{Identified by Warden security-review · 3EJ-ELU}