# Add a GitHub Pages Deploy Workflow to an Eleventy Site

Yes. An agent turns your Eleventy site's build into a GitHub Pages deploy workflow with the right path prefix, a build check on pull requests, and pinned actions.

[Run this on Rush](https://cloud.getrush.ai/run/add-deploy-workflow/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 and where it expects to live. In a site laid out like 11ty/eleventy-base-blog, `package.json` has a `build` script of `npx @11ty/eleventy` and a `build-ghpages` script that adds `--pathprefix=/eleventy-base-blog/`, with Eleventy 3 and `engines.node` at 18 or newer, and `.nvmrc` says 22. `eleventy.config.js` registers `HtmlBasePlugin`, which is what rewrites absolute URLs when a path prefix is set, excludes `draft` pages in build mode through `ELEVENTY_RUN_MODE`, writes to `_site`, and runs the image transform plugin over every post. `netlify.toml` publishes `_site` with `npm run build`. `.github/dependabot.yml` updates npm monthly with a seven-day cooldown and has a `github-actions` block commented out. `.github/workflows/gh-pages.yml.sample` is a complete Pages workflow in waiting: on push to `main`, a `build` job that checks out, sets up Node 22, caches `~/.npm` and Eleventy's `.cache`, runs `npm ci` and `npm run build-ghpages` and uploads `_site/` with `upload-pages-artifact`, then a `deploy` job with `pages: write` and `id-token: write` that runs `deploy-pages`, every action pinned to a commit SHA with its version in a comment. Its header comments tell a person to rename it, set the path prefix to the repository name, and switch the Pages source to GitHub Actions.

The agent does the renaming and the two edits the comments describe. It reads the repository name from the clone's origin and sets `--pathprefix` in `build-ghpages` to that name, or removes the flag when a `CNAME` file in `public/` shows the site has a custom domain. The sample becomes `.github/workflows/gh-pages.yml` with its SHA pins kept, `permissions` moved so the `build` job has `contents: read` only, and a `concurrency` group on the deploy job so two pushes in quick succession do not race.

A deploy that only runs on `main` catches a broken build after it lands, so the agent adds a `pull_request` trigger that runs the `build` job alone, with the deploy job conditioned on the push event. Drafts stay out of both because `ELEVENTY_RUN_MODE` is `build` in CI. The commented `github-actions` block in `dependabot.yml` is enabled so the SHA-pinned actions get update pull requests.

In its sandbox the agent runs `npm ci` and `npm run build-ghpages`, then greps `_site/index.html` and a post page for the prefixed `href` and `src` values that `HtmlBasePlugin` should have written, and checks the feed and sitemap URLs the config generates from `metadata.js`. It runs `actionlint` over the workflow and opens the pull request, noting that switching the Pages source to GitHub Actions in the repository settings is the one step a person must do.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a GitHub Pages deploy workflow to this Eleventy site. Read package.json, .nvmrc, eleventy.config.js, netlify.toml, _data/metadata.js, .github/dependabot.yml and every file under .github/workflows first, including any .sample file. Turn the sample into .github/workflows/gh-pages.yml, keeping its commit-pinned actions: set the pathprefix in the build-ghpages script to this repository's name, or drop the flag if a CNAME file shows a custom domain; give the build job contents: read only; add a concurrency group on deploy; add a pull_request trigger that runs only the build job; and enable the github-actions block in dependabot.yml. Run npm ci and npm run build-ghpages in the sandbox and check the built HTML for prefixed URLs. Run actionlint and open a pull request that explains the one settings change a person must make to point Pages at GitHub Actions.",
  "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 renames the sample to `.github/workflows/gh-pages.yml` and edits it, changes the `build-ghpages` line in `package.json`, and uncomments the `github-actions` block in `.github/dependabot.yml`. Its description lists the path prefix it chose and where it read it from, the permissions per job, the `actionlint` result, and the prefixed URLs it found in the built pages in its sandbox.

Once merged and the Pages source set to GitHub Actions, a push to `main` builds and deploys the site, a pull request gets a build check without deploying, and Dependabot proposes updates to the pinned actions on its monthly schedule.

Before merging, a reviewer checks the path prefix against the URL the site will live at, decides whether the deploy should also run on a manual `workflow_dispatch`, and confirms the Eleventy `.cache` directory is the right thing to cache for the image and fetch plugins in use.

## Run it on every new site

A team that starts each docs or blog site from the same template sends this body once per new repository from its own server, each a `POST /o/{org}/sessions` with 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. Each run reads its own name and files, so the path prefix is never copied from the template, and a site with a custom domain gets no prefix at all.

Once the workflow exists, an automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if the build job failed on this pull request, read the Eleventy output and comment with the template and the error" starts one run per pull request. The trigger adds the pull request after the prompt, and the run comments and pushes nothing.

## Why run it on Rush?

The sample workflow is right for exactly one repository name, and the usual failure is a site deployed with the template's prefix so every stylesheet and image link is broken. The agent reads the name from the repository, builds with it, and reads the built HTML to show the prefix landed, all in its own sandbox before the workflow ever runs on GitHub.

The build output, the grep of the generated pages and the `actionlint` output stay with the run as proof. A team spinning up several sites starts one run per repository at once, each in its own sandbox with its own `node_modules` and Eleventy cache.

## Frequently asked questions

### What if my site uses a custom domain?

A `CNAME` file in `public/` is copied to `_site/` by the passthrough rule, and it means the site serves from the domain root. The agent then removes `--pathprefix` from `build-ghpages`, as the sample's own comments describe, so URLs are not prefixed with the repository name.

### Why keep the commit-pinned actions?

The sample pins each action to a SHA with the version in a comment, which is the safer form. The agent keeps those pins and enables the `github-actions` block in `dependabot.yml` so they are updated by pull request rather than going stale.

### Do drafts get published?

No. The preprocessor in `eleventy.config.js` drops pages with `draft: true` when `ELEVENTY_RUN_MODE` is `build`, which is what both the deploy and the pull request job run.

### Is there anything the workflow cannot do by itself?

Pointing the repository's Pages source at GitHub Actions is a setting a person changes once. The pull request describes where it is; until it is set, the deploy job's `deploy-pages` step fails with a message that says so.

## More Eleventy jobs

- [Add Giscus Comments to an Eleventy Blog](https://getrush.ai/run/add-giscus-comments/eleventy/)
- [Set Up GitHub Actions CI for an Eleventy Site](https://getrush.ai/run/add-github-actions-ci/eleventy/)
- [Add i18n to an Eleventy Blog](https://getrush.ai/run/add-i18n/eleventy/)

## The same job on other stacks

- [Deploy Firebase Functions from GitHub Actions](https://getrush.ai/run/add-deploy-workflow/firebase-functions/)
- [Add a GitHub Pages Deploy Workflow to a Hugo Site](https://getrush.ai/run/add-deploy-workflow/hugo/)
- [Add a GitHub Pages Deploy Workflow to a Jekyll Site](https://getrush.ai/run/add-deploy-workflow/jekyll/)

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