# Add a Build Check for a Docusaurus Site on Every Pull Request

Yes. An agent adds a job to your Docusaurus pull request workflow that builds the default locale the way your deploy does, proves it first and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-docs-build-check/docusaurus/). 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 adds a check, because a Docusaurus site with translations and mirrored content can be built several wrong ways. In a site laid out like electron/website, `package.json` runs Docusaurus 3.10.0 with `@docusaurus/faster`, pins `packageManager` to Yarn 4.10.3 with `enableScripts: false` and `nodeLinker: node-modules` in `.yarnrc.yml`, and sets `engines.node` to 24 with `.nvmrc` at 24.22.1 while `README.md` still says Node 22. Its `build` script is `docusaurus build --locale en`; the eight-locale build is a separate `i18n:build` script, and `i18n/*` is gitignored except the English source. `docs/latest/` holds 301 Markdown files mirrored from electron/electron by a webhook, with an `.sha` file the config reads into a `docs-sha` meta tag, and `scripts/pre-build.ts` is only for pulling a different docs branch by hand. `lint` runs `tsc --noEmit`, `oxfmt`, `oxlint` and `markdownlint-cli2`; `lint:sidebars` runs `scripts/check-sidebars.ts`, which checks every API doc on disk has a sidebar entry and every id in `sidebars.js` exists, and is not part of `lint`.

Then it reads the two workflows. `.github/workflows/pull-request.yml` checks out, sets up Node from `.nvmrc` with the Yarn cache, runs `yarn install --immutable` and `yarn lint`, and stops there: no pull request builds the site. `push-main.yml` does, on push and twice a day: it restores an `actions/cache` entry for `.docusaurus` and `**/.cache` keyed on `yarn.lock` and the hashes of every JavaScript and TypeScript file, registers `.github/problem-matchers/docusaurus.json` so `[WARNING]` lines become annotations, runs `yarn build` with `GITHUB_TOKEN` in the environment because the API history tables resolve Electron versions through GitHub, and syncs `build/` to Azure Blob Storage while excluding the seven translated directories. A broken MDX file, a sidebar id that no longer exists or a transformer that throws is therefore found by the publish job after merge, not by the pull request.

The agent adds a `build` job to `pull-request.yml` that copies the publish job's steps up to the build and nothing after: the same checkout and Node setup, `yarn install --immutable`, the same cache keys so a pull request warms the cache the publish job reads, the problem matcher, `yarn lint:sidebars` since no job runs it, and `yarn build` with `GITHUB_TOKEN`. The job gets a `concurrency` group on the pull request number with `cancel-in-progress`, a `timeout-minutes` set from the time the sandbox build took, and `permissions: contents: read` as the existing job has. It builds the English locale only, as the `build` script already does, and the pull request explains why: the translated locales come from Crowdin on their own schedule and are built by `update-i18n-deploy.yml`.

Before writing the job the agent runs the sequence in its own sandbox on Node 24.22.1: `yarn install --immutable`, `yarn lint:sidebars`, then `yarn build`. It records how long the build took and which `[WARNING]` lines it printed, since `docusaurus.config.ts` sets `onBrokenLinks` to `warn` and those warnings are annotations rather than failures. It also fixes the stale Node 22 sentence in `README.md`, since the workflow, `.nvmrc` and `engines` all say 24.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a build check for this Docusaurus site on every pull request. Read package.json, .nvmrc, .yarnrc.yml, docusaurus.config.ts, sidebars.js, scripts/check-sidebars.ts, scripts/pre-build.ts, README.md, .github/problem-matchers/docusaurus.json and every workflow under .github/workflows first. Add a build job to .github/workflows/pull-request.yml that sets up Node from .nvmrc with the yarn cache, runs yarn install --immutable, restores the same .docusaurus cache the push-main workflow uses with the same keys, registers the Docusaurus problem matcher, runs yarn lint:sidebars and then yarn build with GITHUB_TOKEN in the environment, with a concurrency group per pull request, contents: read permissions and a timeout. Build only the default locale as the build script does. Run yarn install, yarn lint:sidebars and yarn build in your sandbox first and record the duration and every warning line. Fix the Node version sentence in README.md to match .nvmrc. Open a pull request with the build output. Do not change push-main.yml, the deploy steps or docusaurus.config.ts.",
  "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

The pull request changes `.github/workflows/pull-request.yml` and one sentence of `README.md`. Its description pastes the tail of the sandbox build with its duration, lists the `[WARNING]` lines the build printed grouped by file, and names the cache key the new job shares with the publish workflow.

The new `build` job runs on the pull request itself, beside the existing `test` job, so a reviewer sees both checks on the same page before merge. `push-main.yml`, the Azure sync and the Crowdin jobs are unchanged, and the problem matcher turns the warnings into annotations on the files that caused them.

Before merging, a reviewer decides whether the timeout leaves enough room for a cold cache, whether `lint:sidebars` should join the `lint` script instead of being its own step, and whether the warnings the build printed are worth a follow-up that sets `onBrokenLinks` to `throw`.

## Run it on every documentation repository

A team that runs several Docusaurus sites sends this body once per repository from its own server: one `POST /o/{org}/sessions` each, with that 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. `GET /o/{org}/github` lists every repository the Rush GitHub App installation can reach, so the script can pick the ones with a `docusaurus.config` file and no build on pull requests. Each run reads its own site: one with a single locale gets a plain `docusaurus build`, one on pnpm gets the pnpm cache, and one whose docs are generated by a `pre-build` step gets that step in the job.

Once the job is merged, the question becomes who reads a red build. An automation on the Project with a `github` trigger on `workflow_run.failure` and the prompt "if the failed workflow is the pull request build, read its log, name the file and line that broke the build and comment on the pull request with the fix" turns the failure into a comment on the pull request that caused it. The trigger adds the event after the prompt, and only work by an owner, member or collaborator fires it.

## Why run it on Rush?

A build job copied from another site guesses at the locale flag, the cache, the token the transformers need and the time the build takes, and the first time it is wrong is on a contributor's pull request. The agent reads the publish workflow that already builds the site, runs the same commands in its own sandbox, and writes the job from a build that completed there.

The build log and its duration stay with the run and are pasted into the pull request, so the review is of a check that has already passed once. The same request runs for every site a team owns at the same time, each reading its own configuration.

## Frequently asked questions

### Why not build every locale?

The `build` script already passes `--locale en`, and the translated locales are not in the repository: `i18n/*` is gitignored except English, and the translations arrive from Crowdin through `update-i18n-deploy.yml`. A pull request build of eight locales would download translations to check a change in English content. The job builds what the repository contains.

### Will the broken-link warnings fail the check?

No. `docusaurus.config.ts` sets `onBrokenLinks` to `warn`, so the build prints `[WARNING]` lines and exits zero, and the problem matcher shows them as annotations. The pull request lists the warnings the sandbox build printed; raising the setting to `throw` is a separate decision the description points at.

### Why does the job need `GITHUB_TOKEN`?

The publish workflow passes it, and the config comments say the API history tables resolve Electron versions through the GitHub API, with an environment token taking precedence over a local `.env`. The job passes the same token with read permissions so the build behaves as it does on main rather than failing or rate-limiting on a runner without one.

### Does the pull request cache slow down or interfere with the publish job?

The job uses the same `actions/cache` path and keys as `push-main.yml`, so a pull request that builds first leaves a warm `.docusaurus` cache the publish job can restore, and the key includes the `yarn.lock` hash so a dependency change starts clean.

## More Docusaurus jobs

- [Add Giscus Comments to a Docusaurus Blog](https://getrush.ai/run/add-giscus-comments/docusaurus/)
- [Add i18n to a Docusaurus Site](https://getrush.ai/run/add-i18n/docusaurus/)
- [Add Lighthouse CI to a Docusaurus Site](https://getrush.ai/run/add-lighthouse-ci/docusaurus/)

## The same job on other stacks

- [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/)
- [Fail CI on Sphinx Warnings and Broken Links for a Python Library](https://getrush.ai/run/add-docs-build-check/python/)

## 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/)
