# Add a GitHub Pages Deploy Workflow to a Jekyll Site

Yes. An agent adds a workflow that builds your Jekyll 4 site from its own Gemfile and deploys it to GitHub Pages, checks the lockfile installs and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-deploy-workflow/jekyll/). 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 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`

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

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

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

## More Jekyll jobs

- [Add Giscus Comments to a Jekyll Site](https://getrush.ai/run/add-giscus-comments/jekyll/)
- [Add Lighthouse CI to a Jekyll Site](https://getrush.ai/run/add-lighthouse-ci/jekyll/)
- [Add Link Checking to a Jekyll Site with html-proofer](https://getrush.ai/run/add-link-checking/jekyll/)

## The same job on other stacks

- [Add a Deploy Workflow for a Lit Component's Docs Site](https://getrush.ai/run/add-deploy-workflow/lit/)
- [Add a GitHub Pages Deploy Workflow to an mdBook](https://getrush.ai/run/add-deploy-workflow/mdbook/)
- [Add a Workflow That Deploys MkDocs Documentation on Every Push](https://getrush.ai/run/add-deploy-workflow/mkdocs/)

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