fix(ci): Lint docs and developer docs in separate jobs

[sentry-junior]

DESCRIBE YOUR PR

pnpm build and pnpm build:developer-docs both write to .next. When a PR touches both docs/** and develop-docs/**, the 404 workflow runs both builds in one job and then starts one server. By then the developer docs build has overwritten the docs build, so only developer docs get checked for broken links.

This change gives each changed site its own job and runner:

• A changes job decides which sites changed.
• One Lint <site> for 404s job runs per changed site, in parallel. Each job builds, starts the server, and runs the linter. The runner is thrown away when the job ends, so the server doesn't need to be stopped and nothing else shares port 3000.
• A small lint-404 job keeps the required check name. It passes when every changed site passes its lint, or when no site changed.

Changes to this workflow or scripts/lint-404s/** now lint both sites, so edits to the workflow check themselves.

An earlier version of this PR handled the shared build with a bash script that started and stopped the server between sites. Separate jobs remove the need for it. PRs that touch both sites also run the two builds in parallel instead of one after the other.

Replaces #19465. That PR's other changes already landed in #19509 (AI Agents doc) and #19526 (cross-site link handling).

IS YOUR CHANGE URGENT?

• Urgent deadline (GA date, etc.): YYYY-MM-DD
• Other deadline: YYYY-MM-DD
• No deadline: Not urgent, can wait up to 1 week+

PRE-MERGE CHECKLIST

• 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

via shannon.anahata.

--

View Junior Session [Sentry]

[vercel]

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

Project	Deployment	Actions	Updated
develop-docs	Ready	Preview	Oct 7, 2026 7:43pm UTC
sentry-docs	Ready	Preview	Oct 7, 2026 7:43pm UTC

[cursor]

This change only alters a 404 lint job. It does not change live pages. The plan has no production signal. An issue escalates if the 404 lint job fails or skips one site.

Not monitored: no services

Mention @change-monitor in a comment to update the plan.

Plan

What changed

The 404 lint job now builds, serves, and lints each site in turn. It no longer lets the second build overwrite the first .next output. No production service must deploy for this change to go live. The new steps run when GitHub runs the 404 lint job.

Risk

If the new script fails, pull requests that touch either site can fail CI. A leftover process can occupy port 3000 and block the second lint. A wait loop can hide a crash until the sitemap probe fails. Wrong process-group cleanup can fail a job that already passed the lint.

Intended effect

The intended effect is a 404 lint of each site after its own build. Production telemetry cannot show that CI behavior. Absent looks like the job still linting only one site. There is no connected GitHub Actions signal.

Regression watch

This diff can break the 404 lint job. It cannot break live pages. A regression is a failed job, a timeout, or a port-in-use error. This session cannot measure those GitHub Actions symptoms. Production error rate and live 404s are not on this path.

Not observable

GitHub Actions results for the 404 lint job, including pass, fail, skip, and duration. This session has no GitHub Actions connector. Production page errors and web vitals are not effects of this diff.

[sfanahata]

@vgrozdanic - I closed the last PR about this as it was really dated and tried again. Can you take another look and let me know if this seems like the right solution now?

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a804c06. Configure here.}

[vgrozdanic]

I tried something similar because the lint took super long, but i am not the biggest fan of scripts/lint-404s/serve-and-lint.sh, it feel really hacky 😅

But worth a try if it speeds up the lints

[sfanahata]

@vgrozdanic - I asked for it to be updated. Here's how it works now

changes job: works out which sites the PR touched.
One lint job per changed site: "Lint docs for 404s" and "Lint developer-docs for 404s". Each runs on its own machine: build, start the server, check links. There's no shared .next folder or port 3000, and no shutdown code, because GitHub throws the machine away when the job ends. When both sites change, the two jobs run at the same time.
lint-404 summary job: keeps the name of the required check on master. It passes only if every site that changed passed, or if nothing changed. It fails if any site's job fails or gets cancelled.

Each site keeps its own Next.js build cache.

This version saves about 4 minutes on build time, however, when running through the check, it was discovered that only 12 pages are currently reviewed on develop-docs because the logic says to follow the sitemap, which explicitly narrows down the pages for indexing/SEO purposes. I'll open a separate PR to change that, and hope that it doesn't blow the build time again.