# Add Lighthouse CI to a Jekyll Site

Yes. An agent adds a workflow that builds your Jekyll site and runs Lighthouse CI on its main pages with assertions and reports, proves it first, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-lighthouse-ci/jekyll/). 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 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`

```json
{
  "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"
    }
  ]
}
```

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 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.

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

- [Add Link Checking to a Jekyll Site with html-proofer](https://getrush.ai/run/add-link-checking/jekyll/)
- [Add llms.txt to a Jekyll Site](https://getrush.ai/run/add-llms-txt/jekyll/)
- [Add Mermaid Diagrams to a Jekyll Blog on GitHub Pages](https://getrush.ai/run/add-mermaid-diagrams/jekyll/)

## The same job on other stacks

- [Add Lighthouse CI to a SolidJS App](https://getrush.ai/run/add-lighthouse-ci/solidjs/)
- [Add Lighthouse CI to a Vite React App](https://getrush.ai/run/add-lighthouse-ci/vite-react/)
- [Add Lighthouse CI to a VitePress Docs Site](https://getrush.ai/run/add-lighthouse-ci/vitepress/)

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