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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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.