What the agent does
The agent reads how the site is built before it adds a job that builds it, because a Docusaurus site with translations can take a long time to build in the wrong way. In a site laid out like helm/helm-www, package.json runs docusaurus build on Docusaurus 3.10 with yarn 1 named in packageManager and a yarn.lock committed, .nvmrc says Node 22, and the root Makefile wraps the build: make build cleans, runs yarn install --frozen-lockfile and yarn run build with SITE_URL and BASE_URL in the environment, and sets NODE_OPTIONS to silence a Web Storage warning on newer Node. docusaurus.config.js reads SITE_URL for url, sets onBrokenLinks and onBrokenAnchors to throw, declares twelve locales in i18n with English as the default, serves three docs versions, a blog with full RSS and Atom feeds, Algolia search, an announcement bar, and a second docs instance for community content whose files are committed and marked noRuntimeDownloads. Deploys go through Netlify, whose netlify.toml publishes the build directory and gives every pull request a deploy preview. The GitHub workflows are build.yml, which only compiles the Go SDK examples, typos.yml, a stale-issue job and a community-docs sync; none of them builds the site, and nothing measures how it performs.
docusaurus build with no --locale flag builds every known locale, so a Lighthouse job that copied make build would build all twelve to audit three English pages. The agent's workflow passes --locale en, which the CLI documents as building only the locales named, and keeps the Makefile's NODE_OPTIONS handling by calling yarn run build --locale en with SITE_URL set to the production address, since Lighthouse's canonical and hreflang audits read the absolute URLs the build writes.
The Lighthouse configuration goes in lighthouserc.js at the root. ci.collect.staticDistDir points at build, so Lighthouse CI serves the directory itself and no startServerCommand is needed; ci.collect.url lists the home page, the install page under docs/intro/install/, one blog post and the blog index, each run more than once so a single noisy sample does not fail the job; ci.upload.target is temporary-public-storage, which the Lighthouse CI documentation describes as public and short-lived, with a note in the pull request on switching to a Lighthouse CI server if the team wants history. For ci.assert, the agent starts from the lighthouse:recommended preset, runs it once in the sandbox, and then sets the audits that fail on the current site to warn with the score each one got in a comment, so the first run is green and the team can tighten one audit at a time; the accessibility and best-practices categories keep an error-level minimum because the site already passes them.
The workflow, .github/workflows/lighthouse.yml, runs on pull requests that touch anything but sdkexamples/: actions/setup-node with the version from .nvmrc and the yarn cache, yarn install --frozen-lockfile, the single-locale build, npm install -g @lhci/cli pinned to a minor line, and lhci autorun. The agent runs that sequence in its sandbox end to end, with the Chrome that Lighthouse needs installed first, and pastes the per-page scores and the list of audits it set to warn into the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add Lighthouse CI to this Docusaurus site. Read package.json, .nvmrc, Makefile, docusaurus.config.js, netlify.toml, sidebars.js and every workflow under .github/workflows first. Write lighthouserc.js with staticDistDir set to build, urls for the home page, docs/intro/install/, the blog index and one blog post, more than one run per page, temporary-public-storage as the upload target, and assertions that start from lighthouse:recommended. Write .github/workflows/lighthouse.yml that runs on pull requests outside sdkexamples, uses the Node version in .nvmrc with the yarn cache, runs yarn install --frozen-lockfile, builds only the en locale with SITE_URL set to the production address, installs @lhci/cli and runs lhci autorun. Install Chrome in the sandbox, run the build and lhci autorun exactly as the workflow does, set every audit that fails on the current site to warn with its score in a comment so the first run passes, and open a pull request with the per-page scores and the list of warned audits. Do not change the Makefile, the Netlify config or the existing workflows.",
"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 adds lighthouserc.js and .github/workflows/lighthouse.yml, and adds .lighthouseci/ to .gitignore. Its description pastes the per-page performance, accessibility, best-practices and SEO scores from the sandbox run, lists each audit set to warn with the score that made it fail the preset, and shows the single-locale build's timing beside a note on what the full twelve-locale build would have done.
The new lighthouse workflow runs on the pull request itself, so the reviewer sees the scores on a GitHub runner and the temporary report links in the job log before merge. Netlify's deploy preview builds as it always has, and the typos, build and stale workflows are unchanged.
Before merging, a reviewer decides which of the warned audits to turn back into errors first, whether the page list should include a versioned docs page and a translated one, and whether to stand up a Lighthouse CI server so scores are kept rather than expiring with the temporary storage.
Run it on every pull request to the site
Once the workflow is merged, GitHub runs Lighthouse on every pull request, and the question becomes who reads a red score. An automation on the Project with a github trigger on workflow_run.failure and the prompt "if the failed workflow is lighthouse, read its log, name the audit and page that failed and the score, and comment on the pull request with the smallest change that would pass it" turns a failed check into a specific comment. Automation runs are read-only, so the comment is all it posts, and only work by an owner, member or collaborator fires it.
A team that runs several documentation sites sends this body once per repository from its own server, each a POST /o/{org}/sessions with the 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. Each run reads its own config: a site with one locale gets no --locale flag, one deployed from GitHub Pages gets BASE_URL set to its project path, and one with a startServerCommand already in a config file gets that reused.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Lighthouse CI is two files, and the second file is the one that bites: a build that compiles every locale for a three-page audit, a url list that misses the pages visitors land on, an assertion preset that fails the first run on audits nobody has looked at. The agent reads the build wrapper and the site config, builds one locale in its own sandbox, runs the audit, and writes the assertions from the scores it saw.
The build log, the Lighthouse run and the scores stay with the run and are pasted into the pull request, so the review is of numbers the site produced rather than of a config that looks reasonable. Several sites get the same treatment at once, each with assertions set from its own baseline.
Frequently asked questions
Why build only the English locale?
Because docusaurus build builds every locale in i18n.locales unless --locale names fewer, and this site lists twelve. The audited pages are English, so the job builds that one and finishes in a fraction of the time. The description notes that auditing a translated page means adding its locale to the flag and its URL to the list.
Will it fail the first pull request?
No. The agent runs lhci autorun with the lighthouse:recommended preset in its sandbox first, and every audit the current site fails is set to warn in lighthouserc.js with its score in a comment. The job passes on day one and shows the warnings, and the team turns them back into errors one at a time.
Where do the reports go?
To Lighthouse CI's temporary public storage, which prints a link per page in the job log and keeps the report for a short time. The documentation calls that storage public, so the pull request says so and names the Lighthouse CI server as the option for private, lasting history.
Does this change how Netlify deploys the site?
No. netlify.toml, the Makefile and the deploy previews are untouched; the new workflow builds its own copy on a GitHub runner and audits that. Netlify keeps building all locales for the real deploy as it does today.
More Docusaurus jobs
The same job on other stacks
- Add Lighthouse CI to an Eleventy Site (Eleventy)
- Add Lighthouse CI to a Gatsby Blog (Gatsby)
- Add Lighthouse CI to a Hugo Docs Site (Hugo)