All jobs

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

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

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

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

The same job on other stacks

Keep reading