Releasing

This page is intended for maintainers publishing admin_suite to RubyGems.

Automated Release Process (Recommended)

The gem is automatically published to RubyGems when changes are merged to main, provided the version has been bumped.

Steps

1. Bump the version
   • Update lib/admin_suite/version.rb
2. Update changelog
   • Add an entry to CHANGELOG.md
3. Create a PR and get it merged
   • The CI workflow will run tests automatically on the PR
   • Once merged to main, after CI passes, the publish workflow will:
     • Check if the version already exists on RubyGems
     • Build and publish the gem (if it’s a new version)
     • Create a Git tag for the release (if it doesn’t already exist)
     • Create a GitHub Release with notes extracted from CHANGELOG.md, or auto-generated from commits since the previous tag if no CHANGELOG entry exists

Requirements

• Trusted Publishing must be configured as described below (merged in PR #49, verified by the successful 0.6.1 publication on September 12).
• The version in lib/admin_suite/version.rb must be unique (not already published)

Trusted Publishing setup

On RubyGems, open the existing admin_suite gem’s Trusted publishers → Create:

Field	Value
Repository owner	techwright-lab
Repository name	admin_suite
Workflow filename	publish.yml
Environment	release

Leave reusable-workflow repository fields blank. In GitHub, create the release environment and restrict it to branch main. Required reviewers are optional; adding them introduces a manual release gate. Keep account MFA enabled.

The publish job uses environment: release, job-scoped id-token: write, and the pinned rubygems/configure-rubygems-credentials action immediately before gem push. The action supplies short-lived OIDC credentials; do not override them with RUBYGEMS_API_KEY or a manually written credentials file.

Automatic publishing accepts only successful CI for this repository’s main-branch pushes, and checks out the exact tested SHA. Manual dispatch is limited to main; it remains an explicit maintainer retry path, not a substitute for checking CI.

After a workflow migration, start the updated workflow on main rather than rerunning a historical attempt with its old workflow definition. Verify the new version on RubyGems, its tag target, and the GitHub Release. Only then remove the obsolete GitHub secret and revoke the old key if no other consumer uses it.

Reference: RubyGems Trusted Publishing.

Manual Release Process

If you need to publish manually:

1. Bump the version
   • Update lib/admin_suite/version.rb
2. Update changelog
   • Add an entry to CHANGELOG.md
3. Run tests and build the gem

bundle exec rake test
gem build admin_suite.gemspec

1. Tag the release

git tag -a "vX.Y.Z" -m "AdminSuite vX.Y.Z"
git push --tags

1. Publish to RubyGems

gem push "admin_suite-X.Y.Z.gem"

Notes

• Manual API-key pushes may require MFA/OTP; Trusted Publishing avoids the interactive prompt without disabling account MFA (this gem retains rubygems_mfa_required).
• The automated workflow uses a GitHub Actions bot to push tags and create GitHub Releases
• Automatic publishing runs after successful main-push CI; maintainers may also manually dispatch on main.
• GitHub Release notes are sourced from the matching version section in CHANGELOG.md; if no entry exists, they are auto-generated from commits since the previous tag; a plain “Release vX.Y.Z” string is used only as a final fallback when no previous tag or commit-generated notes are available
• You can manually trigger the publish workflow from the GitHub Actions tab if needed