What the agent does
The agent reads how the site expects to be built, because that decides whether GitHub Pages' own pipeline or a workflow is the right deploy. In a site on Poole, as in poole/poole, the Gemfile names jekyll, jekyll-gist, jekyll-paginate and jekyll-seo-tag with no versions, the gemspec requires jekyll ~> 4.0, and Gemfile.lock resolves Jekyll to 4.0.0 with sassc 2.2.1 and ffi 1.11.3 under Bundler 2.0.2. _config.yml sets url: https://getpoole.com, baseurl: "", permalink: pretty, paginate: 1, a plugins list with the same three gems and an exclude list for the Gemfile, lockfile, README and licence. There is no .ruby-version, no .github/workflows/ beyond a release-notes.yml that runs release-drafter on pushes to master, and no CNAME. The Pages pipeline builds with the github-pages gem, whose published versions list pins Jekyll 3.10.0; this site asks for Jekyll 4, so the pipeline would build it with a different major than the one the lockfile records. A workflow builds with the repository's own Bundler environment instead.
The workflow follows GitHub's Jekyll starter, pages/jekyll.yml in actions/starter-workflows, updated to the action versions current at the time of the run. .github/workflows/pages.yml runs on push to master, the branch the release-notes workflow already names, and on workflow_dispatch, with permissions of contents: read, pages: write and id-token: write, and a concurrency group named pages with cancel-in-progress: false so a deploy in flight finishes. The build job checks out, runs ruby/setup-ruby with bundler-cache: true and a Ruby version the agent writes into a new .ruby-version file so the two never drift, runs actions/configure-pages to learn the site's base path, builds with bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" under JEKYLL_ENV: production, and uploads _site with actions/upload-pages-artifact. The deploy job needs build, targets the github-pages environment and runs actions/deploy-pages, whose page_url output becomes the environment's link. The --baseurl flag is what lets the same configuration serve a project page under <user>.github.io/<repo> and a custom domain at the root, so baseurl in _config.yml stays empty.
The lockfile is the part that fails quietly. A Gemfile.lock written for Jekyll 4.0.0 in 2019 pins native gems built for the Ruby of that time, and bundler-cache: true runs bundle install against it on whatever Ruby the workflow names. The agent installs that Ruby in its sandbox and runs bundle install with the lockfile as it is; if sassc or ffi will not build, it runs bundle update and reads the result, which moves Jekyll within the ~> 4.0 constraint the gemspec allows and may swap the Sass converter for the one newer Jekyll 4 releases depend on, and it puts the lockfile change in the pull request as its own commit with the list of gems that moved. It then builds with JEKYLL_ENV=production bundle exec jekyll build and checks _site/ has the four posts under their pretty permalinks, about/, archive/, the page2/ pagination directory, atom.xml, styles.css and 404.html.
Before opening the pull request the agent serves _site/ on a local port and opens the home page and a post in its own browser to confirm the stylesheet and the seo tags render, then runs actionlint on the new workflow. It adds a .github/dependabot.yml entry for github-actions so the action majors move by pull request, and a README section with the local build command and the one step it cannot take: switching the Pages source to GitHub Actions under the repository's Settings, Pages, which needs an admin on github.com and which the pull request names first.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a GitHub Actions workflow that builds this Jekyll site with its own Gemfile and deploys it to GitHub Pages. Read the Gemfile, Gemfile.lock, _config.yml, the gemspec if there is one, the existing workflows and the root pages first. Write .github/workflows/pages.yml from GitHub's Jekyll starter with current action versions: a build job with ruby/setup-ruby and bundler-cache, actions/configure-pages, bundle exec jekyll build with --baseurl from the configure-pages output and JEKYLL_ENV production, and actions/upload-pages-artifact; a deploy job on the github-pages environment with actions/deploy-pages; permissions contents read, pages write and id-token write; and a pages concurrency group that does not cancel in progress. Add a .ruby-version matching the Ruby the workflow uses and a dependabot entry for github-actions. In the sandbox install that Ruby, run bundle install against the existing lockfile and, only if it fails, bundle update within the Gemfile's constraints in a separate commit; then build, check the output has every post and page, serve it and open it in the browser, and run actionlint. In the pull request say that the Pages source must be switched to GitHub Actions by hand and why a workflow build is used instead of the Pages pipeline for this Gemfile.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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 .github/workflows/pages.yml, .ruby-version, .github/dependabot.yml and a README section, and changes Gemfile.lock only if the old one would not install, in a commit of its own that lists what moved. No layout, include, post or _config.yml key changes. Its description quotes the bundle install or bundle update output, the jekyll build summary, the list of files found in _site/, the browser screenshot from the run's record, and the reason this site is built by a workflow rather than by the Pages pipeline: a Gemfile on Jekyll 4 where the pipeline's github-pages gem pins Jekyll 3.10.
A reviewer checks that the workflow's branch matches where they merge, that the Ruby in .ruby-version is one they want to maintain, and that the Pages setting has been switched before merge, because the first run fails at configure-pages on a repository still set to deploy from a branch. After merge, the first push builds the site on the runner, uploads _site as the github-pages artifact and deploys it, and the environment shows the live URL.
Run it on every Jekyll site deployed by hand
A team that keeps several Jekyll sites sends this body once per repository from its own server, each POST /o/{org}/sessions naming one repository in resources and carrying 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 Gemfile: a site on the github-pages gem gets a note that the Pages pipeline already builds it and a workflow only if the team wants the build log, a site with a .ruby-version keeps it, and a site with a CNAME gets the custom-domain explanation in its pull request.
The key's webhook_url reports each run the key starts with the pull request URL in result, so a script that sent five requests collects five pull requests without polling.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A Pages workflow for Jekyll is a copy of a starter file until it meets a real Gemfile, and that is where it breaks: a lockfile that will not install on the runner's Ruby, a plugin the Pages pipeline allows but at another Jekyll major, a baseurl that is right for one hosting and wrong for the other. The agent runs bundle install and the real jekyll build in its own sandbox with the Ruby the workflow names, opens the output in a browser and keeps the commands and output in the run's record, so the pull request shows the build that will run rather than a file that should work.
It also keeps decisions separate: the lockfile update, if one is needed, is its own commit with its own list of moved gems, so a reviewer can accept the workflow and question the gems, or the other way round. Several sites with different Gemfiles get several pull requests, each fitted to its lockfile and branch.
Frequently asked questions
Why not let GitHub Pages build the site itself?
The Pages pipeline builds with the github-pages gem, which pins Jekyll 3.10 and a fixed plugin list, so a site whose Gemfile asks for Jekyll 4 would be built with a different major than the one it was written for. The workflow runs bundle exec jekyll build with the repository's own gems, and its log is on the Actions tab when a build fails.
Will the old Gemfile.lock work?
The agent finds out by running bundle install on the Ruby the workflow uses. If native gems from the lockfile's era fail to build, it runs bundle update within the Gemfile's constraints and puts the new lockfile in a separate commit with the list of changes, so the reviewer sees exactly which gems moved and why.
What does the --baseurl flag do?
actions/configure-pages reports the path the site will be served under, empty for a user site or custom domain and /<repo> for a project site, and the build passes it to Jekyll as --baseurl. That keeps baseurl in _config.yml empty and lets the same configuration work on either hosting without editing it.
Does the agent switch the Pages source for me?
No. Choosing GitHub Actions as the Pages source happens under the repository's Settings, Pages, and needs an admin on github.com. The pull request says so first; until it is done the workflow's configure-pages step fails on its first run.
Why a .ruby-version file?
So the Ruby the workflow builds with and the Ruby a contributor runs locally are the same, read from one file by ruby/setup-ruby and by version managers alike. Without it the workflow hard-codes a version that drifts from the laptops that produced the lockfile.