Repository navigation
test: docs preview end to end (do not merge) - #32098
Closed
nickvigilante wants to merge 14 commits into
Closed
nickvigilante wants to merge 14 commits into
nickvigilante wants to merge 14 commits into
Conversation
Docs previews at coder.com/docs/@<branch> share coder.com's origin and cookies with the real site. Publish each PR's docs instead as its own site on Vercel's domain, which is on the Public Suffix List: coder-docs-pr-<number>.vercel.app for the PR head and coder-docs-pr-<number>-<sha>.vercel.app for every built commit. docs-pr-preview-deploy builds with docs-engine's offline export in three jobs, so PR content never runs beside a secret: engine mints a short-lived docs-engine read token and packs the source pinned in docs/.engine-ref; build has no secrets and compiles the PR's docs/; deploy, in the docs-preview environment, lays the static files out with the engine's script (verified against the engine job's digest), adds X-Robots-Tag: noindex, deploys prebuilt, sets both aliases and keeps one PR comment. Branch PRs build on every push; fork PRs build only when a maintainer adds the docs-preview label, and each new push removes it. docs-pr-preview-cleanup deletes a PR's previews when it closes and grooms previews of closed PRs weekly. docs-preview's per-page links now point at the PR's preview site. Assisted-by: AI
A fork build in a pull_request_target run shares the base branch's Actions cache scope, so a fork could poison main's cache, and it would sit beside the private engine source. Drop the fork path: no pull_request_target build or label handling, and every job requires the head repository to be this one. The cleanup keeps pull_request_target: closed, which checks out and runs nothing from the PR. vercel.app names are first-come across all Vercel accounts, so anyone could claim a preview's name before the deploy or after cleanup. Build every preview URL from the repository variable DOCS_PREVIEW_DOMAIN instead, and fail when it is unset or a vercel.app name. docs-preview.yaml is now a reusable workflow that the deploy workflow calls after a successful deploy, so its per-page links never point at a preview that does not exist yet. Assisted-by: AI
Move docs/.engine-ref from e3c55c2 to 5584d67. The newer engine refuses a docs root that is a symbolic link, renders search hits without raw HTML, drops author-chosen heading ids that could break hydration, and pins Node to the patched 22.23.4 release. The build commands the preview runs (`turbo run build --filter=@coder/offlinedocs` and `scripts/build-output.mjs`) are unchanged at that commit. Assisted-by: AI
- Refuse a docs/ tree with symbolic links before the build, and a static export holding anything but regular files and directories before the job with the Vercel token copies and uploads it. - Print changed reference page paths with only allowlisted characters, since a PR-chosen file name could otherwise read as a "##[" workflow command. - Build the comment's links from the validated domain, and test that the domain still comes from vars.DOCS_PREVIEW_DOMAIN. - Use docs-preview.cdr.dev in the examples and test fixtures. - Run Node 22.23.4, as the engine pins, and move harden-runner, create-github-app-token and upload-artifact to the pins the rest of the repository uses. Assisted-by: AI
The preview domain is the team's Vercel domain coderite.app, read as before from vars.DOCS_PREVIEW_DOMAIN. Only the header comment and the test fixtures name it. Assisted-by: AI
The new docs launched on coder.com from docs-engine main today, so previews should build with the same engine. The commands this workflow runs (the offlinedocs build and its build:output script) are unchanged since the previous pin. Assisted-by: AI
docs/.engine-ref comes from the pull request, so the PR chooses which docs-engine commit runs. Once docs-engine is public, a commit pushed to any fork of it can be fetched by SHA through coder/docs-engine, so a format check alone would let a PR build with unreviewed engine code. The engine job now checks out full history and fails before packing unless the pinned commit is an ancestor of docs-engine main. Assisted-by: AI
Previews move off coderite.app, which also hosts login-protected internal sites, to docs.cdr-preview.dev, a domain used only for previews. The domain still comes from DOCS_PREVIEW_DOMAIN; only the comments and test fixtures named the old one. Since the domain is now docs-only, the aliases drop their coder-docs- prefix: pr-<n> for the PR head and pr-<n>-<sha:0:9> per commit. The deploy, comment and cleanup workflows build the same names. Assisted-by: AI
Assisted-by: AI
The preview token is scoped to the one preview project. Vercel CLI 59.3.0 looks up the token's user and team before every command and gives up when the team lookup returns 403, so vercel pull failed with "Could not retrieve Project Settings" although the token can read the project. 65.11.0 skips that lookup and pulls the project's settings with the same token. It is the newest release more than a week old. Assisted-by: AI
Throwaway change to exercise the docs-preview comment's per-page links on a real page. Not for merging. Assisted-by: AI
nickvigilante
temporarily deployed
to
docs-preview
November 12, 2026 16:49 — with
GitHub Actions
Inactive
Contributor
Docs preview deploymentThis pull request's head: https://pr-32098.docs.cdr-preview.dev Every built commit keeps its own preview, newest first: Previews are not indexed by search engines and are deleted when this pull request is merged or closed. |
Contributor
Docs previewLinks open this pull request's preview at https://pr-32098.docs.cdr-preview.dev, which updates with each push. Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here. Preview sites for each built commit (1)Every built commit keeps its own preview, newest first. Previews aren't indexed by search engines and are deleted when this pull request is merged or closed. |
Assisted-by: AI
nickvigilante
temporarily deployed
to
docs-preview
November 12, 2026 17:29 — with
GitHub Actions
Inactive
nickvigilante
temporarily deployed
to
docs-preview
November 12, 2026 19:16 — with
GitHub Actions
Inactive
This branch was previously deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Do not merge. This is a throwaway PR that tests the docs PR previews from #30698 end to end with an ordinary docs change. Close it once the checks below are done.
It targets #30698's branch rather than
main, so its diff is a single reworded sentence indocs/install/index.md(a page with a route indocs/manifest.json), and the deploy, comment and cleanup workflows that run are #30698's.What to check
docs-pr-preview-deployrun passes all four jobs:engine,build,deployandcomment.https://pr-<this PR>.docs.cdr-preview.devand one per-commit URL.docs/install/index.mdwith a link tohttps://pr-<this PR>.docs.cdr-preview.dev/installand a checkbox. Ticking the checkbox and pushing again keeps it ticked.After closing
The cleanup workflow runs from
main's copy, which doesn't have it until #30698 merges, so closing this PR won't delete its preview. Delete the deployment taggedpr=<this PR>in thecoder-docs-pr-previewVercel project by hand, or leave it for the weekly groom once #30698 is onmain.🤖 Built with AI assistance.