# 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 Rush](https://cloud.getrush.ai/run/add-github-actions-ci/eleventy/). 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 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`

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

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

- [Add i18n to an Eleventy Blog](https://getrush.ai/run/add-i18n/eleventy/)
- [Show a Last Updated Date from Git History on Eleventy Posts](https://getrush.ai/run/add-last-modified-dates/eleventy/)
- [Add Lighthouse CI to an Eleventy Site](https://getrush.ai/run/add-lighthouse-ci/eleventy/)

## The same job on other stacks

- [Set Up GitHub Actions CI for an Expo App](https://getrush.ai/run/add-github-actions-ci/expo/)
- [Set Up GitHub Actions CI for an Express App](https://getrush.ai/run/add-github-actions-ci/express/)
- [Set Up GitHub Actions CI for a Flask App](https://getrush.ai/run/add-github-actions-ci/flask/)

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