# Add a Build Check for a VitePress Docs Site on Every Pull Request

Yes. An agent adds a GitHub Actions workflow that installs with pnpm and runs the VitePress build, which fails on dead links, proves it first and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-docs-build-check/vitepress/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the site is built and deployed before it writes a workflow. In a site like vuejs/docs, `package.json` has `dev`, `build` and `preview` scripts that call `vitepress`, a `type` script that runs `vue-tsc --noEmit`, and a `preinstall` hook of `npx only-allow pnpm`. It pins `packageManager` to pnpm 10.33.0, requires Node 20 or later in `engines`, depends on `vitepress` 2.0.0-alpha.17 with a pnpm override that maps its `vite` to version 8.0.7, and lists `vitepress-plugin-llms` and `vitepress-plugin-group-icons` as dev dependencies. `netlify.toml` builds with `pnpm run build` on Node 24 and publishes `.vitepress/dist`, and `vercel.json` only sets cache headers and rewrites. The only workflow in `.github/workflows/` is `automerge.yml`, which auto-merges Dependabot updates to `@vue/theme`. `.vitepress/config.ts` sets `srcDir` to `src`, excludes `tutorial/**/description.md`, and never sets `ignoreDeadLinks`, so a build fails on a dead internal link by default. A pull request today gets no check at all; a broken link or a failing build is found by the deploy.

Then it writes `.github/workflows/ci.yml`. It runs on `pull_request` and on `push` to the default branch, with a `concurrency` group keyed on the ref and `cancel-in-progress: true` so a force-push cancels the stale build. The job checks out the repository, sets up pnpm through `pnpm/action-setup`, which reads the version from `packageManager`, sets up Node 24 to match `netlify.toml` with `cache: pnpm`, runs `pnpm install --frozen-lockfile` so a lockfile drift fails loudly, and runs `pnpm run build`. Because `ignoreDeadLinks` is unset, that one step is also the dead-link check: VitePress stops the build and prints every dead link with its source file.

The type check is added only if it passes today. The agent runs `pnpm run type` in its sandbox first; if `vue-tsc` is clean it becomes a second step, and if it reports existing errors the agent leaves it out and lists the errors in the pull request, because a check that is red on day one gets ignored. It does the same for the build itself: it runs `pnpm run build` on the current default branch, reads the dead-link output if there is any, and either confirms a clean build or lists the links so the team can decide whether to fix them or add targeted entries to `ignoreDeadLinks`.

The workflow is linted with `actionlint`, the `automerge.yml` workflow is left as it is, and a sentence is added to the Contributing section of `README.md` saying pull requests run the build. The agent does not touch `.vitepress/config.ts`, the content under `src/` or the deploy configuration, so the only change in behaviour is that a pull request now shows a check.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a build check for this VitePress site. Read package.json, netlify.toml, vercel.json, .vitepress/config.ts, README.md and the existing workflow under .github/workflows first. Write .github/workflows/ci.yml that runs on pull requests and on pushes to the default branch with a concurrency group that cancels stale runs, sets up pnpm from the packageManager field, sets up Node 24 with the pnpm cache, runs pnpm install --frozen-lockfile and then pnpm run build. Run pnpm run build in the sandbox first and record whether it passes or which dead links it reports; do not set ignoreDeadLinks. Run pnpm run type too, and add it as a step only if it passes today, otherwise list its errors in the pull request. Run actionlint on the new workflow, leave automerge.yml and the content untouched, add one sentence to the README's Contributing section, and open a pull request that quotes the build result.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that adds `.github/workflows/ci.yml` and one sentence to `README.md`. The description quotes the result of `pnpm run build` on the current branch, either the final line of a clean build or the dead-link list VitePress printed with each source file, says whether `vue-tsc` was clean and therefore added as a step, and names Node 24 and the pnpm version the workflow uses and where each came from.

The run's record keeps the `pnpm install --frozen-lockfile` output, the full VitePress build log, the `vue-tsc` output and the `actionlint` result, so a reviewer can see the exact commands the workflow will run already ran once in a clean environment.

Before merging, a reviewer checks the pull request's own workflow run is green, decides what to do with any dead links the build reported, and confirms the Node version matches what Netlify builds with so the check and the deploy cannot disagree.

## Run it on every documentation repository

A team that owns several VitePress sites sends this body once per repository to `POST /o/{org}/sessions`, each with its own repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started rather than a second pull request. Each run reads that site's own `package.json` and deploy configuration, so a site on npm and Node 20 gets a workflow that matches it rather than a copy of this one.

After the workflow is merged, no Rush run is needed per pull request: GitHub runs the build check itself. A `webhook_url` on the key reports each setup run as `run.completed` with the pull request in `result`, and a `run.failed` names the site whose build does not pass today and needs a person first.

## Why run it on Rush?

A workflow written without running it is a guess about the package manager, the Node version and whether the build passes at all. The agent installs with the real lockfile, runs the real VitePress build and the real `vue-tsc` in its own sandbox, and the first time the check is red is in that sandbox, with the dead links listed, not on a contributor's first pull request.

The build log stays with the run and is quoted in the pull request, so the team decides about existing dead links with the list in front of them, and the reviewer's only job is to confirm the check runs green on the pull request that adds it.

## Frequently asked questions

### Will it set ignoreDeadLinks to make the build pass?

No. The prompt forbids it, because the dead-link failure is the point of the check. If the current branch has dead links, the pull request lists them and the team chooses between fixing them and adding specific patterns to `ignoreDeadLinks` in `.vitepress/config.ts`.

### Why Node 24 when engines says 20 or later?

Because `netlify.toml` sets `NODE_VERSION` to 24, and a check that builds with a different Node than the deploy can pass while the deploy fails. The agent reads the deploy configuration and matches it, and names the source in the pull request.

### Does the check replace the Netlify deploy preview?

No. The preview still builds and publishes the site; the workflow adds a required-check candidate that fails fast on a broken build or a dead link, before anyone opens the preview. The two run the same `pnpm run build` command.

### Why is the type check optional?

The agent runs `pnpm run type` first and adds it only if `vue-tsc` is clean today. A step that fails on the day it is added teaches contributors to ignore the check, so existing errors are listed in the pull request for a separate fix instead.

## More VitePress jobs

- [Add Draft Posts to a VitePress Blog](https://getrush.ai/run/add-draft-posts/vitepress/)
- [Add Giscus Comments to a VitePress Blog](https://getrush.ai/run/add-giscus-comments/vitepress/)
- [Add Last Updated Dates to a VitePress Blog](https://getrush.ai/run/add-last-updated-dates/vitepress/)

## The same job on other stacks

- [Add a Build Check for a Docusaurus Site on Every Pull Request](https://getrush.ai/run/add-docs-build-check/docusaurus/)
- [Build an mdBook on Every Pull Request Before It Deploys](https://getrush.ai/run/add-docs-build-check/mdbook/)
- [Add a Strict Docs Build Check to MkDocs Docs](https://getrush.ai/run/add-docs-build-check/mkdocs/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
