All jobs

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 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 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 with this body:

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

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

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

The same job on other stacks

Keep reading