All jobs

Set Up GitHub Actions CI for an Eleventy Site

Yes. An agent adds a GitHub Actions workflow that builds your Eleventy site with npm ci on every pull request, validates the output HTML and links, and opens a PR.

Run this on RushOpens 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 builds. In a starter like 11ty/eleventy-base-blog, package.json is an ES module project ("type": "module") whose build script is npx @11ty/eleventy, with build-ghpages adding --pathprefix=/eleventy-base-blog/, start serving with --serve --quiet, and debug and benchmark setting DEBUG=Eleventy* through cross-env. There is no test or lint script. engines asks for Node 18 or newer and .nvmrc says 22. The dev dependencies are @11ty/eleventy ^3.1.7, @11ty/eleventy-img, @11ty/eleventy-navigation, @11ty/eleventy-plugin-rss, @11ty/eleventy-plugin-syntaxhighlight, luxon, prismjs and zod, locked in a package-lock.json at lockfile version 3, so npm ci is the install command. netlify.toml publishes _site after npm run build, and vercel.json only sets trailingSlash.

There is no workflow yet, but there is a template for one: .github/workflows/gh-pages.yml.sample, a deploy-only workflow that runs on push to main, checks out with Node 22, caches ~/.npm and the Eleventy .cache directory, runs npm ci and npm run build-ghpages, and publishes _site/ with upload-pages-artifact and deploy-pages, every action pinned to a commit SHA with the version in a comment. The README points to it. The agent keeps that file as it is, since it is a deploy path the reader may or may not enable, and writes a separate ci.yml that runs on pull_request and on push to main, with the same pinning style and the same two caches, but keyed on package-lock.json rather than package.json so the npm cache invalidates when the lock changes.

The build itself is the first test. eleventy.config.js sets content as the input, _site as the output and _includes and _data beside them; a drafts preprocessor drops any page with draft: true when ELEVENTY_RUN_MODE is build; _data/eleventyDataSchema.js validates that front matter with zod and throws on a bad value, so a typo in draft fails the build. The image transform plugin runs with failOnError: false, which means a missing image warns rather than fails, and the feed plugin writes /feed/feed.xml. After npm run build the workflow checks that _site/index.html, _site/feed/feed.xml and _site/sitemap.xml exist, runs html-validate over _site/**/*.html, and runs a link checker over the output directory for internal links only, since _data/metadata.js still has https://example.com/ as the site URL and external checks would be noise on a fresh site. The built _site is uploaded as a workflow artifact so a reviewer can download what a pull request would publish.

In the sandbox the agent runs the same steps itself on Node 22: npm ci, npm run build, the three file checks, the validator and the link checker, and fixes what the starter's own output trips, for example by adding an .htmlvalidate.json that relaxes rules the generated syntax-highlighted code blocks cannot satisfy, with each relaxed rule named in the pull request. It also runs npm run build-ghpages once to confirm the path-prefixed build still works, since the sample deploy workflow depends on it.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add GitHub Actions CI to this Eleventy site. Read package.json, package-lock.json, .nvmrc, eleventy.config.js, the _data directory, netlify.toml and .github/workflows/gh-pages.yml.sample first. Write .github/workflows/ci.yml that runs on pull requests and on pushes to the default branch, uses the Node version from .nvmrc, caches ~/.npm keyed on package-lock.json and the Eleventy .cache directory, installs with npm ci, runs npm run build, checks that the index page, the feed and the sitemap exist in _site, validates the generated HTML, checks internal links in the output, and uploads _site as an artifact. Pin every action to a commit SHA with its version in a comment, the way the sample workflow does, and leave the sample deploy workflow unchanged. Run every step yourself first and fix any validator findings in the templates or with a documented config. Open a pull request that lists each check and what it found.",
  "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

What comes back is a pull request with .github/workflows/ci.yml, an .htmlvalidate.json if the validator needed one, and possibly a one-line fix in a layout under _includes/layouts/ if the validator found something real in a template. The sample deploy workflow, netlify.toml and vercel.json are untouched, so the site deploys exactly as before.

The description lists the steps in order with the output each produced in the sandbox: the npm ci and npm run build summaries from Eleventy, the three existence checks, the validator's findings and how each was resolved, and the link checker's count of internal links followed. The full transcript, every command and its output, is at GET /o/{org}/sessions/{id}/messages.

The pull request is the first one the new workflow runs on, so a reviewer sees it as a check on the pull request itself before reading the YAML. They confirm the Node version matches .nvmrc, that the action SHAs correspond to the versions in the comments, and that no validator rule was turned off without a reason in the description.

Run it on every terminal hand-off

A writer who runs the site from a laptop starts this from the terminal with this body and goes back to the post they were drafting. The run reads the real package.json, lock file and Eleventy config, so the workflow it writes matches the Node version, the install command and the output directory of this site rather than a template's.

Send a request_id, a UUID, with the body so a retried start returns the run it already began. The pull request link is on the run's GET /o/{org}/sessions/{id} answer once it is open, and a key with a webhook_url hears run.completed when the turn ends.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A CI workflow written cold tends to fail on its first run for a boring reason: the wrong Node version, npm install instead of npm ci, a validator rule that rejects every page of generated code. The agent runs each step in a sandbox with the real site first, with the same Node the .nvmrc names, so the workflow that reaches the pull request has already passed once and the pull request can show it.

Every command and its output are kept on the run, so the pull request's claims about what the validator and link checker found are backed by the transcript rather than by a description. Several Eleventy sites can be handled at once, each in its own sandbox, each with its own pull request.

Frequently asked questions

Will this change how my site deploys?

No. The workflow builds and checks; it deploys nothing. gh-pages.yml.sample is left as the README describes it, and Netlify and Vercel keep reading netlify.toml and vercel.json. If you enable the GitHub Pages workflow later, the CI job runs alongside it.

Does it check external links?

Not by default. The starter's _data/metadata.js still points at https://example.com/, and external checks fail for reasons unrelated to a pull request. The link check covers links within _site; a follow-up can turn on external checks with an allowlist once the site has a real domain.

Why both caches?

They cache different things. ~/.npm saves downloading packages on every run, keyed on the lock file so a dependency bump refreshes it. Eleventy's .cache directory holds fetched remote assets and image transforms, which the sample deploy workflow also caches, and reusing it keeps builds fast as the site grows.

What if a validator finding is in content I did not write?

Generated markup from the syntax highlighting plugin or the image transform can trip a strict rule. The agent fixes template problems in the templates and, for generated output, adds a rule-level exception in .htmlvalidate.json, named in the pull request, rather than disabling the validator.

More Eleventy jobs

The same job on other stacks

Keep reading