Repository navigation
ci: build docs PR previews on per-PR preview sites - #30698
Merged
Merged
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
nickvigilante
had a problem deploying
to
docs-preview
October 28, 2026 21:47 — with
GitHub Actions
Failure
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
nickvigilante
had a problem deploying
to
docs-preview
November 10, 2026 17:48 — with
GitHub Actions
Failure
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
nickvigilante
had a problem deploying
to
docs-preview
November 12, 2026 15:58 — with
GitHub Actions
Failure
Assisted-by: AI
nickvigilante
had a problem deploying
to
docs-preview
November 12, 2026 16:16 — with
GitHub Actions
Failure
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
nickvigilante
temporarily deployed
to
docs-preview
November 12, 2026 16:28 — with
GitHub Actions
Inactive
Contributor
Docs preview deploymentThis pull request's head: https://pr-30698.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. |
Engineers found two bot comments per docs PR too noisy. The deploy job no longer posts its own "Docs preview deployment" comment. It passes the built commit to docs-preview.yaml, whose existing comment gains a collapsible list of every built commit's preview, newest first, read back from the comment on each run and capped at 100. docs-preview.yaml already posts nothing, and deletes its comment, when a PR changes only generated reference pages or no page or image, so a reference-only or non-docs PR now gets no comment at all. The deploy job's pull-requests permission drops to read. Assisted-by: AI
nickvigilante
temporarily deployed
to
docs-preview
November 12, 2026 17:26 — with
GitHub Actions
Inactive
ianjevans
approved these changes
Nov 12, 2026
ianjevans
left a comment
Collaborator
There was a problem hiding this comment.
I like the per-commit previews as well as the overall. I'm 50/50 whether the links should be target=_blank.
nickvigilante
temporarily deployed
to
docs-preview
November 12, 2026 19:10 — with
GitHub Actions
Inactive
Collaborator
Author
|
@ianjevans I'm indifferent. I'll merge this as-is and then launch a new PR for opening those links in a new tab (we should have an external link icon next to each link to signal to contributors and reviewers that it opens in a new tab). |
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.
Docs previews at
coder.com/docs/@<branch>share coder.com's origin and cookies with the real site. This publishes each pull request's docs as its own site ondocs.cdr-preview.dev, a domain used only for previews (repository variableDOCS_PREVIEW_DOMAIN), and points the existingdocs-previewcomment's per-page links and checkboxes at it.URLs
https://pr-<n>.docs.cdr-preview.dev: the PR head, re-aliased on every build. A slower build of an older commit doesn't take it back.https://pr-<n>-<first 9 of sha>.docs.cdr-preview.dev: one per built commit, listed newest first in a collapsible "Preview sites" list in the PR's docs preview comment, so reviewers can step through the branch.vars.DOCS_PREVIEW_DOMAIN(aliases, comment links, cleanup); nothing hard-codes the domain. Previews moved offcoderite.app, which also hosts login-protected internal sites, so a preview page whose content any coder/coder writer controls would have been same-site with them.cdr-preview.devhosts nothing else, and the docs previews sit underdocs.so other preview kinds can get their own subdomain later. The jobs fail with a clear error if it is unset or avercel.appname, because*.vercel.appnames are first-come across all Vercel accounts and anyone could claim a preview's name before our deploy or after cleanup frees it.apps/offlinedocs/vercel.json, plusX-Robots-Tag: noindex, which the deploy job prepends to the Build Output APIconfig.jsonroutes without touching the existing ones.pr=<n>and its aliases are deleted. A weekly groom (Mondays 07:23 UTC, alsoworkflow_dispatch) deletes previews of any closed PR, in case a close event was missed.Who gets previews
Only PRs from a branch in coder/coder, on every push that touches
docs/**. Every job in the deploy workflow, and the close path of the cleanup, requiresgithub.event.pull_request.head.repo.full_name == github.repository.Fork PRs get no preview for now. Building fork content in a
pull_request_targetrun would share the base branch's Actions cache scope, so a fork could poison main's cache, and it would sit beside the private engine source. Fork previews come in a follow-up once the build runs in a no-network sandbox (or the public builder kit ships). That follow-up will gate on a maintainer stating the exact approved commit, not on a label, so a push after approval can't slip in.One comment, posted only after a deploy
docs-preview.yamlis now a reusable workflow (workflow_callonly). The deploy workflow'scommentjob calls it afterdeploysucceeds, so the per-page links never point at a preview that doesn't exist yet. I chose this over moving the per-page logic into the deploy job: the existing comment logic and its mapper test stay as they are, and only the trigger changes.Each PR gets at most one bot comment. The deploy job posts nothing; it passes the built commit (
short_sha) todocs-preview.yaml, which adds a collapsible "Preview sites for each built commit" list to its comment, newest first, read back from the comment on each run and capped at 100. That comment is only posted when a non-generated page or an image changed: a PR that changes onlydocs/reference/**(generated CLI and API pages), or nothing previewable, gets no comment, and an earlier one is deleted. Engineers found the earlier two-comment version too noisy. If the comment is deleted that way and a later push brings it back, its commit list starts over; the earlier previews still exist until the PR closes.Three jobs, so PR content never runs beside a secret
engine: checksDOCS_PREVIEW_DOMAINfirst, reads the docs-engine commit pinned indocs/.engine-ref(from the PR head, falling back to the base for a branch that predates the pin), mints a short-lived token from a GitHub App installed only on coder/docs-engine, downscoped tocontents: readon that one repository, checks out withpersist-credentials: false, and uploads a tarball plus its sha256 as a job output. Never touches PR content.build: no secrets,contents: readonly. Verifies the engine tarball against the digest, sparse-checks out the PR'sdocs/, refuses adocs/that is or contains a symbolic link (one could pull runner files, such as the private engine source, into a public preview), buildsapps/offlinedocswithDOCS_ROOTas docs-engine's owndocs-pr-preview.ymldoes, and uploads only the staticout/export.deploy: in thedocs-previewenvironment withVERCEL_PREVIEW_TOKEN. Verifies the engine tarball against the digest again (a compromised build job could replace an artifact, but not a job output), refuses an export holding anything but regular files and directories, lays the static files out with the engine'sbuild:outputscript, adds noindex, runsvercel deploy --prebuiltwith metaprandsha, and sets both aliases through the Vercel API. It holds onlypull-requests: read, for the check that the PR head hasn't moved before re-aliasing; thecommentjob posts the comment. It runs the engine's trusted script rather than takingconfig.jsonfrom the build job, because a Build Output directory from another job could carry serverless functions or rewritten routes.docs-pr-preview-cleanup.yamlkeepspull_request_target: closedso a PR can't change its own cleanup; it checks out nothing and runs no PR content, only Vercel and GitHub API calls. Fork PRs have no previews, so their close is skipped.PR-chosen strings never reach a log line unfiltered: the comment workflow prints changed reference-page paths with every character outside a path allowlist as
?, so a file name can't forge a::or##[workflow command, and the deploy job's errors name no path.Engine pin
docs/.engine-refnow pins docs-enginemainateadb477, the enginecoder.com/docslaunched with on 2026-10-28 (wase3c55c2; an earlier revision of this PR pinned5584d67). The commands the workflow runs are unchanged between them.e3c55c2already had thebuild:outputscript, but the newer engine refuses a symlinked docs root, renders search hits without raw HTML, drops author-chosen heading ids that could break hydration, and pins Node 22.23.4, which the build and deploy jobs now use too. The commands the workflow runs (pnpm turbo run build --filter=@coder/offlinedocsandapps/offlinedocs/scripts/build-output.mjs) are unchanged at5584d67.The pin must be a commit on docs-engine
main. Theenginejob checks docs-engine out with full history and fails before packing unlessgit merge-base --is-ancestor "$REF" origin/mainpasses. Once docs-engine is public, a commit pushed to any fork of it can be fetched by SHA throughcoder/docs-engine, so the 40-hex format check alone would let a PR build with unreviewed engine code.test-docs-preview-mapper.shpins that the check runs in theenginejob, before the pack step, against a full-history checkout.Before this can run
Checked on 2026-11-12: IT registered
cdr-preview.devin Vercel on teamteam_tGkWfhEGGelkkqUUm9nXq17r, with Vercel nameservers, so*.docs.cdr-preview.devneeds no DNS or wildcard step. IT also setdocs.cdr-preview.devas thecoder-docs-pr-previewproject's own preview deployment suffix and removedcoderite.appfrom it, so the project's generated deployment URLs land on the preview domain too, not on the team'scoderite.appsuffix; the first deploy will confirm that. The project has Vercel Authentication and password protection off. The secretsDOCS_ENGINE_APP_IDandDOCS_ENGINE_APP_PRIVATE_KEYexist.DOCS_PREVIEW_DOMAINis set todocs.cdr-preview.dev. Thedocs-previewenvironment exists (created 2026-10-28) with no protection rules and no branch policy, and holdsVERCEL_PREVIEW_ORG_IDandVERCEL_PREVIEW_PROJECT_ID, andVERCEL_PREVIEW_TOKENwas stored on 2026-11-12.DOCS_ENGINE_APP_IDis installed on coder/docs-engine only ("Only select repositories") with Repository permissions Contents: Read-only and Metadata: Read-only and nothing else, at https://github.com/organizations/coder/settings/installations. The workflow also downscopes each token tocontents: readon docs-engine, so the installation is the outer bound.enginejob anddocs-preview.yamlrun outside it:gh variable set DOCS_PREVIEW_DOMAIN -R coder/coder --body docs.cdr-preview.devcoder-docs-pr-preview(prj_RiVa1voPHmsfbEXkasFDXmYqAr0L): checked on 2026-11-12,ssoProtectionandpasswordProtectionboth reportenabled: false.cdr-preview.devregistered with Vercel nameservers, anddocs.cdr-preview.devset as the project's preview deployment suffix.200,404and403. Create it at https://vercel.com/account/settings/tokens, scoped to thecoder-docs-pr-previewproject only (vercel tokens create --projectis refused for non-owners). Then check, with the new token in$VERCEL_PREVIEW_TOKEN, that it can list the project's deployments (200), reach the team-level alias API (404, not403), and cannot see the productioncoder-docsproject (403or404, never200):docs-previewenvironment: it exists with no branch policy (becausepull_requestruns on the merge ref) and its two variables are set. Only the token is left:gh secret set VERCEL_PREVIEW_TOKEN -R coder/coder --env docs-previewgh secret setprompts for the token so it stays out of shell history.docs.cdr-preview.dev, which hosts nothing else, so they are no longer same-site with the login-protected sites oncoderite.app. Previews are same-site with each other, so one PR's preview could set a cookie the others receive. Anything added tocdr-preview.devlater should stay outsidedocs.and not rely on cookies scoped to the parent domain. The docs CSP allows inline scripts, and any coder/coder writer controls a preview's content.VERCEL_PREVIEW_TOKENby editing the workflow on a branch, as with any secret apull_requestdeploy uses. The token is scoped to the one preview project to bound that; required reviewers on the environment would close it, at the cost of an approval per preview.docs/.engine-ref, so the engine code that lays out the export in the deploy job is PR-chosen, but only among commits on docs-enginemain. It runs before, not in, the step that holds the token.Testing
test-docs-preview-mapper.shchecks thatdocs-preview.yamlreads the domain fromvars.DOCS_PREVIEW_DOMAIN, builds links onpr-<n>.<domain>from the validated value with nocoder.com/docs/@orvercel.applink, and runs only as a reusable workflow called afterdeploy. It also checks the per-commit list (this commit first, earlier ones carried, repeats and other PRs' lines dropped, capped at 100), that the list round-trips through the comment it renders without touching checkbox state, and that the deploy job posts no comment and passes its commit on. All 58 checks pass (run with GNU coreutils, sed, grep and awk on macOS); the new workflow check failed before the change.actionlintat the repo's pinned commit, with ShellCheck, reports nothing, and so does the repo's pinned zizmor 1.11.0 (--strict-collection --persona=regular). The noindex step was run against aconfig.jsonfrom docs-engine's realbuild-output.mjs: the route count went from 11 to 12 with the CSP route intact. With the variable, environment and token in place, theengineandbuildjobs pass on this PR, including the check that the pinned engine commit is on docs-enginemain. The first deploy failed atvercel pullwith "Could not retrieve Project Settings": Vercel CLI 59.3.0 looks up the token's team (403 for a project-scoped token) and gives up, although the token reads the project (200). Run locally with the same token, 65.11.0 skips that lookup and pulls the settings, so the workflow now pins 65.11.0, the newest release more than a week old. The deploy, alias and cleanup calls have not completed in CI yet.🤖 Built with AI assistance.