# Add a Release Workflow for a Jekyll Theme Gem

Yes. An agent adds a tag-triggered workflow that checks the version, builds on both Jekyll majors, publishes the theme gem with trusted publishing, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-release-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 theme is packaged and tested. In a theme laid out like daattali/beautiful-jekyll, `beautiful-jekyll-theme.gemspec` sets the version to a literal string, `6.0.1`, selects its files from `git ls-files` by a pattern covering `assets`, `_layouts`, `_includes`, `_data`, `feed`, `404`, `tags`, `staticman`, the license and the readme, and declares runtime dependencies on `jekyll` 3.9.3 or later, `jekyll-paginate`, `jekyll-sitemap`, `kramdown`, `kramdown-parser-gfm` and `webrick`, with `appraisal` and `rake` for development. `Appraisals` defines two sets, Jekyll 3.9.4 and 4.3.3, and `.github/workflows/ci.yml` installs them with `bundle exec appraisal install` on Ruby 3.3, builds the site for each with `JEKYLL_ENV=production`, and uploads a Pages artifact. `.gitignore` drops `Gemfile.lock` and `beautiful-jekyll-theme-*.gem`, so releases are built by hand with `gem build` and pushed from a maintainer's machine.

The same version string appears in two more places: a comment on line 24 of `_layouts/base.html` that stamps every generated page, and `CHANGELOG.md`, whose top section is titled `Unreleased version` above the `v6.0.1 (2023-06-08)` entry. The README carries a RubyGems version badge, and the gemspec's `metadata` points `changelog_uri` at the theme's updates page. Nothing checks that those strings agree, and nothing publishes the gem.

The agent writes `.github/workflows/release.yml`, triggered by a push of a tag matching `v*`. Its first job, `verify`, strips the `v` from the tag and compares it with the version in the gemspec and the stamp in `_layouts/base.html`, failing with both values printed when they differ, then runs the same `appraisal install` and the two `appraisal jekyll build` passes `ci.yml` runs, so a release never ships a theme that one Jekyll major cannot build. Its second job, `publish`, needs `verify`, sets `permissions` to `id-token: write` and `contents: write`, installs Ruby 3.3 with `ruby/setup-ruby` and `bundler-cache`, and calls `rubygems/release-gem`, pinned to a release, which builds the gem from the gemspec and pushes it to RubyGems with an OIDC token instead of a stored API key.

The job then creates a GitHub release for the tag with `softprops/action-gh-release`, pinned, using the matching section of `CHANGELOG.md` as its body and the built `.gem` file as an asset. Because the gemspec collects files with `git ls-files`, the agent runs `gem build beautiful-jekyll-theme.gemspec` in its sandbox from the checkout and reads the packed file list to confirm `assets/`, the layouts and includes are inside and `_posts/`, `index.html` and the screenshot are not, and notes in the pull request that the first tag needs the trusted publisher configured once on rubygems.org, with the repository and workflow filename, which the API cannot do for the maintainer.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a release workflow for this Jekyll theme gem. Read the gemspec, Gemfile, Appraisals, CHANGELOG.md, _layouts/base.html, .gitignore and .github/workflows/ci.yml first. Write .github/workflows/release.yml triggered by tags matching v*. Its verify job compares the tag with the gemspec version and the version stamp in _layouts/base.html, failing with both values printed when they differ, then runs the same appraisal install and the appraisal jekyll build passes ci.yml runs. Its publish job needs verify, sets id-token: write and contents: write, installs Ruby 3.3 with ruby/setup-ruby and bundler-cache, publishes with rubygems/release-gem pinned to a release, and creates a GitHub release whose body is the CHANGELOG section for that version and whose asset is the built gem. Run gem build from the checkout in the sandbox and list the packed files in the pull request. Run actionlint over the workflow and open a pull request that explains the one-time trusted publisher setup on rubygems.org.",
  "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/release.yml` and nothing else in the theme itself; no version is bumped and no tag is pushed. Its description lists the packed file list from the sandbox `gem build`, the `actionlint` result, the two Jekyll versions the verify job builds against, and the steps a maintainer takes once on rubygems.org to register the repository and the workflow filename as the gem's trusted publisher.

From the next tag on, a release is one `git tag v6.1.0 && git push --tags`: the verify job refuses a tag whose number does not match the gemspec or the layout stamp, the two builds prove the theme still renders on Jekyll 3 and 4, and the publish job pushes the gem and writes the GitHub release with the changelog section as its notes. No API key is stored in the repository's secrets.

Before merging, a reviewer checks that the tag pattern matches how the changelog names versions, decides whether the workflow should also replace the `Unreleased version` heading with the tag and date in a follow-up commit, and whether the GitHub release should be a draft until a maintainer reads the notes.

## Run it on every tag

A maintainer who looks after several Jekyll themes or plugins sends this body once per repository from a terminal or a small script, 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 gemspec: a gem whose version lives in `lib/<name>/version.rb` gets the check pointed there, and one without `Appraisals` gets a single build on the Jekyll version its lockfile resolves.

Once the workflow exists, an automation on the Project with a `github` trigger on `pull_request.closed.merged` and the prompt "if this merged pull request added a line under Unreleased version in CHANGELOG.md, say in a comment whether the gemspec version and the base layout stamp still match the last tag, and which bump the entries suggest" starts one run per merge. The trigger adds the pull request after the prompt, and its runs read the repository and comment rather than push, so the maintainer learns before tagging when a version string was left behind.

## Why run it on Rush?

A release workflow for a gem is a handful of YAML and a long list of things to get right: the OIDC permission, the version strings that must agree, the file list a gemspec built from `git ls-files` actually packs, and the two Jekyll majors a theme promises to support. The agent builds the gem in a sandbox from a real checkout, runs both Jekyll builds, and writes the workflow from what it found rather than from a template.

The `gem build` output, the packed file list and the two build logs stay with the run, so the reviewer sees the artifact the workflow will publish before any tag exists. A maintainer with several gems runs the same request across all of them at once, each in its own sandbox, and gets one workflow per repository fitted to that gem's versioning.

## Frequently asked questions

### Does the workflow need a RubyGems API key in the repository secrets?

No. `rubygems/release-gem` uses the job's OIDC token, which the `id-token: write` permission enables, and rubygems.org accepts it once the gem's trusted publisher names this repository and workflow file. That registration is a one-time step on rubygems.org that the pull request describes.

### What stops a release with the wrong version number?

The verify job strips the `v` from the tag and compares it with the gemspec version and the comment in `_layouts/base.html`; a mismatch fails the job with both values printed before anything is built or published. Deleting the tag, fixing the strings and tagging again is the whole recovery.

### Why build the site twice before publishing?

The gemspec allows Jekyll 3.9.3 and later and `Appraisals` pins one version of each major, so the release job runs the same two builds `ci.yml` runs. A theme that renders on Jekyll 4 but breaks on 3 is caught by the tag, not by a user's first `bundle update`.

### Which files end up in the gem?

Those `git ls-files` returns that match the gemspec pattern: assets, layouts, includes, data, the feed, the 404 page, the tags page, staticman, the license and the readme. The demo posts, `index.html` and the screenshot are not matched, and the agent lists the packed files in the pull request so a reviewer can confirm that.

## More Jekyll jobs

- [Add Search to a Jekyll Site](https://getrush.ai/run/add-search/jekyll/)
- [Add a Sitemap to a Jekyll Site](https://getrush.ai/run/add-sitemap/jekyll/)
- [Add JSON-LD Structured Data to a Jekyll Site](https://getrush.ai/run/add-structured-data/jekyll/)

## The same job on other stacks

- [Add an npm Release Workflow to a Lit Component](https://getrush.ai/run/add-release-workflow/lit/)
- [Add a Release Workflow for a Maven Library](https://getrush.ai/run/add-release-workflow/maven/)
- [Add a GitHub Release Workflow to an Obsidian Plugin](https://getrush.ai/run/add-release-workflow/obsidian-plugin/)

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