What the agent does
The agent reads how the site is built in CI before adding an audit, because Lighthouse has to run against the same _site the deploy publishes. In a site like github/choosealicense.com, the Gemfile pins jekyll ~> 4.3, resolved to 4.4.1 in Gemfile.lock, with jekyll-github-metadata, jekyll-redirect-from, jekyll-seo-tag, jekyll-sitemap and jekyll-polyglot, and a test group with html-proofer 5.2.1, licensee, rspec and rubocop. .ruby-version is 4.0.5. _config.yml sets url to https://choosealicense.com, declares seven languages with en as default_lang at the site root and the rest under a prefix, keeps assets, favicon.ico, robots.txt and CNAME out of localization, and defines a licenses collection with a /licenses/:path/ permalink and 47 entries. The site's own CI is .github/workflows/test.yml, which runs ./script/cibuild on Ruby 4.0.5: bundle exec rake test builds the site, runs the specs and runs HTMLProofer over _site with Links, Images and Scripts checks, then rubocop. deploy.yml builds with BUNDLE_WITHOUT: development:test, JEKYLL_ENV: production, PAGES_REPO_NWO and JEKYLL_GITHUB_TOKEN, then publishes through configure-pages, upload-pages-artifact and deploy-pages. spec/ci_ruby_version_spec.rb asserts that the Set up Ruby steps of exactly those two workflows match .ruby-version and that the deploy excludes the development and test groups. Dependabot updates the pinned actions weekly as one group.
What Lighthouse will see is in the templates. _includes/header.html loads a Google Fonts stylesheet for Chivo:900 before the site's own assets/css/application.css, prints a rel="alternate" hreflang link for every language plus x-default, and calls {% seo %}; _includes/footer.html writes the rule annotations as inline JSON and loads assets/js/app.js on license pages and assets/js/i18n.js everywhere. assets/css/application.scss imports hint.css from the assets/vendor directory that Bower manages, and the home page uses assets/img/home-sprite.png and its @2x version. The pages worth auditing are index.html at /, licenses.html at /licenses/, a license page such as /licenses/mit/, its translation at /fr/licenses/mit/, and /non-software/.
The agent writes lighthouserc.json at the root: ci.collect.staticDistDir is ./_site, so Lighthouse CI serves the built site itself and no server step is needed, with url entries for the five pages above and a small numberOfRuns; ci.assert starts from the lighthouse:recommended preset and sets the accessibility, best-practices and seo category scores as errors at a floor, performance as a warning, and turns the render-blocking-resources and uses-rel-preconnect audits down to warnings because the fonts request in the header trips both; ci.upload.target is temporary-public-storage so each run links a report. Then it writes .github/workflows/lighthouse.yml on pull_request and workflow_dispatch, with permissions: contents: read: checkout with submodules: true, ruby/setup-ruby with ruby-version: 4.0.5 and bundler-cache, BUNDLE_WITHOUT: development:test so neither HTMLProofer nor RuboCop is installed, bundle exec jekyll build with JEKYLL_ENV: production and PAGES_REPO_NWO so jekyll-github-metadata resolves the repository, then treosh/lighthouse-ci-action@v12 with configPath: ./lighthouserc.json and uploadArtifacts: true. The step is named Set up Ruby and pinned by SHA like the other workflows, even though the version spec only reads test.yml and deploy.yml.
To prove it, the agent sets up Ruby the way .devcontainer/post-create.sh does, installing the build packages and rbenv and the version in .ruby-version, runs bundle install, then JEKYLL_ENV=production bundle exec jekyll build and npx @lhci/cli@0.15.1 autorun against _site with the sandbox's Chrome. It reads the assertion results per URL, lowers no threshold to pass, and records which audits warn on the fonts stylesheet and the home sprite. It runs bundle exec rake test once more to show HTMLProofer and the specs are untouched by a JSON file and a workflow they never read, and bundle exec rubocop because cibuild runs it.
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 Jekyll site. Read Gemfile, Gemfile.lock, .ruby-version, _config.yml, Rakefile, script/cibuild, .github/workflows/test.yml, .github/workflows/deploy.yml, spec/ci_ruby_version_spec.rb, _includes/header.html, _includes/footer.html and .devcontainer/post-create.sh first. Write lighthouserc.json with staticDistDir set to _site and URLs for the home page, the licenses index, one license page, that page in one translation and the non-software page; start from the lighthouse:recommended preset, make the accessibility, best-practices and seo category scores errors with a floor, performance a warning, and demote the render-blocking and preconnect audits that the Google Fonts stylesheet in the header triggers; upload to temporary public storage. Write .github/workflows/lighthouse.yml on pull_request and workflow_dispatch with contents read permission, a checkout with submodules, a Set up Ruby step on the version in .ruby-version with bundler-cache and the development and test groups excluded, a production jekyll build with PAGES_REPO_NWO set, and treosh/lighthouse-ci-action v12 with the config path and artifact upload, pinned by SHA like the other workflows. Install Ruby here as the devcontainer script does, build the site, run lhci autorun against _site, then run bundle exec rake test and rubocop. Open a pull request with the per-URL assertion results.",
"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.json and .github/workflows/lighthouse.yml and changes nothing else. Its description lists each audited URL with the assertions that passed and the ones that warn, names the two audits the fonts stylesheet trips, and shows that rake test and rubocop still pass.
On the pull request, Build and Test runs as before, and the new Lighthouse workflow builds the site a second time without the test gems, audits the five pages and uploads the reports as an artifact with a public link per page. The run's record keeps the sandbox's own lhci autorun output for comparison.
Before merging, a reviewer decides whether a performance floor should be an error now that the baseline is known, whether to add the translated home page or another language's license page to the URL list, and whether the audit should also run on pushes to gh-pages, the branch deploy.yml publishes from, so the deployed site has a report of its own.
Run it on every Jekyll site in your organization
An organization with several Jekyll sites starts one run per repository from its own server: a POST /o/{org}/sessions each, with this prompt as input, 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. GET /o/{org}/github lists every repository the Rush GitHub App installation reaches, so the script can pick the ones with a _config.yml and no lighthouserc. Each run reads its own build, so a site built by the native Pages build rather than a workflow gets a jekyll build step written from its Gemfile, and a site with no translations gets a shorter URL list.
A team that tracks site work in Linear runs the same prompt from an automation in the Project with a linear trigger on issues labelled performance. The trigger adds the issue after the prompt, so an issue that names the page a customer complained about, or the score the team wants to hold, reaches the agent with that number, and the pull request links back to it.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A Lighthouse baseline is only honest when it comes from a production build, and getting one means the right Ruby, the site's gems, a Chrome and the Lighthouse CI tool, which is an afternoon on a laptop that is not already set up for it. The agent builds the site in its own sandbox the way the devcontainer script does, runs the audit, and keeps the per-URL results with the run, so the thresholds in the pull request are the ones the site actually met.
The same prompt runs across every Jekyll site at once, each in its own sandbox with its own pull request, and the site's own checks, HTMLProofer, the specs and RuboCop, run there first so the audit arrives without breaking anything else.
Frequently asked questions
Does the Ruby version spec constrain the new workflow?
spec/ci_ruby_version_spec.rb reads only test.yml and deploy.yml, so a third workflow passes it whatever it does. The agent still names the step Set up Ruby, uses the version from .ruby-version and excludes the development and test groups, so when the maintainers bump Ruby the new file is found by the same search and changed with the others.
Why audit a translated page?
jekyll-polyglot renders every page once per language under its prefix, with the hreflang links in the header pointing across them, and a regression in a translation's layout or a missing alternate shows up only on a localized URL. One translated license page in the list catches that without auditing all seven languages.
Will the Google Fonts request fail the audit?
The stylesheet link in _includes/header.html triggers the render-blocking and preconnect audits, so those are set to warn rather than error and the pull request says so. Self-hosting the font or adding a preconnect hint would clear them, which is a change to the site rather than to its CI and is left for the maintainers.
Does it need a running server?
No. With staticDistDir pointing at _site, Lighthouse CI starts its own static server over the build output, which is how /licenses/mit/ resolves to the index.html the permalink writes. The same configuration works locally after bundle exec jekyll build.
Where do the reports go?
To temporary public storage, which prints a link per URL in the job log, and to the workflow's artifacts through uploadArtifacts. A team that wants history keeps a Lighthouse CI server and swaps the upload target for its address and a token stored as a secret.
More Jekyll jobs
The same job on other stacks
- Add Lighthouse CI to a SolidJS App (SolidJS)
- Add Lighthouse CI to a Vite React App (Vite + React)
- Add Lighthouse CI to a VitePress Docs Site (VitePress)