Skip to content

test: docs preview end to end (do not merge) - #32098

Closed
nickvigilante wants to merge 14 commits into
mainfrom
vigilante/docs-preview-test
Closed

nickvigilante wants to merge 14 commits into
mainfrom
vigilante/docs-preview-test

Conversation

@nickvigilante

Copy link
Copy Markdown
Collaborator

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 in docs/install/index.md (a page with a route in docs/manifest.json), and the deploy, comment and cleanup workflows that run are #30698's.

What to check

  1. The docs-pr-preview-deploy run passes all four jobs: engine, build, deploy and comment.
  2. A "Docs preview deployment" comment links https://pr-<this PR>.docs.cdr-preview.dev and one per-commit URL.
  3. The docs-preview comment lists docs/install/index.md with a link to https://pr-<this PR>.docs.cdr-preview.dev/install and a checkbox. Ticking the checkbox and pushing again keeps it ticked.
  4. Both links open without a Vercel login, and the install page shows "each phase produces the information you need for the next phase".

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 tagged pr=<this PR> in the coder-docs-pr-preview Vercel project by hand, or leave it for the weekly groom once #30698 is on main.


🤖 Built with AI assistance.

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
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
nickvigilante temporarily deployed to docs-preview November 12, 2026 16:49 — with GitHub Actions Inactive
@github-actions

Copy link
Copy Markdown
Contributor

Docs preview deployment

This 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.

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Docs preview

Links 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.

@nickvigilante
nickvigilante temporarily deployed to docs-preview November 12, 2026 17:29 — with GitHub Actions Inactive
Base automatically changed from vigilante/docs-pr-previews to main November 12, 2026 19:10
@nickvigilante
nickvigilante temporarily deployed to main November 12, 2026 19:10 — with GitHub Actions Inactive
@nickvigilante
nickvigilante temporarily deployed to docs-preview November 12, 2026 19:16 — with GitHub Actions Inactive
@nickvigilante
nickvigilante temporarily deployed to main November 12, 2026 19:16 — with GitHub Actions Inactive
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 12, 2026

This branch was previously deployed

2 inactive deployments
docs-preview — e269466f Deployed Nov 12, 2026 by nickvigilante via cleanup #2
main — e269466f Deployed Nov 12, 2026 by nickvigilante via cla #255228
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant