Releasing

Verify an installed gem artifact and publish its matching version tag through RubyGems trusted publishing.

After reading this guide, you will know:

  • How to check a release artifact outside the checkout.
  • Which settings bind RubyGems to the release workflow.
  • How a version tag publishes the gem and its documentation.

Verify the Package

bundle exec rake
bundle exec bundle-audit check --update
bundle exec rake build
bundle exec ruby bin/verify-package --rails --audit
docs/bin/build.sh

The package check installs dependencies in a fresh temporary gem home and requires the installed artifact from outside the checkout. It verifies the core entrypoint, shipped templates and guides, and input parsing. With --rails, it invokes the documented generator and migrates its table up and down in SQLite. With --audit, it checks the actually activated core dependencies against the advisory database.

These checks make no live provider call. Keep provider and client interoperability evidence in Compatibility.

Configure Trusted Publishing

Before the first tag, register a pending trusted publisher on RubyGems with gem name ruby_llm-ag_ui, GitHub owner yorzi, repository ruby_llm-ag-ui, workflow release.yml, and environment release. The workflow uses a short-lived GitHub OIDC identity instead of a stored RubyGems API key.

Prepare the Release Commit

Match the version in lib/ruby_llm/ag_ui/version.rb and docs/_config.yml. Set released: true, add a dated CHANGELOG section, update Release History, and record upgrade steps in Upgrading. For a minor release, add its What’s New guide.

Push the completed commit to main and wait for CI to pass. Tag that exact commit:

git tag -a v0.1.0 -m "Release 0.1.0"
git push origin v0.1.0

Replace the example tag with the version you are releasing. The Release Gem workflow rejects a tag that differs from the gem or docs version, or lacks a CHANGELOG section. It runs offline checks, the advisory audit, and isolated package verification before publishing.

Confirm Publication

On success, the workflow creates a GitHub Release with the gem, checksum, and CHANGELOG notes. The Docs workflow runs after the release workflow succeeds. It publishes the tagged version at / and current main at /next/.

Check the version on RubyGems, the GitHub Release assets, and the documentation installation command. If a publish attempt fails, inspect its logs before retrying. A published RubyGems version cannot be overwritten.