Ruby Gem Release

Release your Ruby gem from GitHub Actions without maintaining custom release scripts or storing a RubyGems API key.

One dispatch updates the changelog, tests and publishes the gem, creates its GitHub Release, and prepares the next development iteration. Choose your version and changelog formats; the workflow handles the sequence.

The default setup below requires Ruby 3.3+, GitHub Actions, and RubyGems Trusted Publishing.

Add ruby-gem-release to the development dependencies and install the standard workflow in your Rakefile. Choose your version file and changelog format explicitly:

require 'ruby-gem-release/workflow/ruby_gem'
require 'ruby-gem-release/changelog'

RubyGemRelease::Workflow::RubyGem.new(
  version: RubyGemRelease::Version::RubyConstant.new(path: 'lib/example/version.rb', constant: 'VERSION'),
  changelog: RubyGemRelease::Changelog::KeepAChangelog.new
).install_tasks

These defaults select the gemspec and repository, reject empty pending notes, prepare the changelog, publish to RubyGems and GitHub Releases, and increment the patch version for the next development iteration. Dates use UTC.

Add .github/workflows/release.yml using the sample workflow, replacing the Ruby version with your project's value:

name: Release

on:
  workflow_dispatch:
    inputs:
      version:
        description: Optional release version overriding the checked-in version.
        type: string
        required: false
      rubygems-owner:
        description: RubyGems account ID for first publication; omit for an existing gem.
        type: string
        required: false

permissions:
  contents: write
  id-token: write

jobs:
  release:
    uses: dblock/ruby-gem-release/.github/workflows/release.yml@v0.5.0
    with:
      ruby-version: '3.3'
      version: ${{ inputs.version }}
      rubygems-owner: ${{ inputs.rubygems-owner }}

In your GitHub repository, open Settings → Environments and create an environment named release. Alternatively, from your repository directory, use gh:

gh api --method PUT repos/{owner}/{repo}/environments/release

For a new gem, open the pending trusted publishers page. For an existing gem, open your existing gem's Trusted publishers page (e.g. https://rubygems.org/gems/example/trusted_publishers). Create a trusted publisher. Set the repository fields to your gem's repository, the workflow filename to release.yml, and the environment to release. Set the separate workflow repository fields to dblock and ruby-gem-release; these identify the reusable workflow RubyGems verifies in the OIDC token.

Collaborators with write access can dispatch releases after this setup, without repository admin access or their own RubyGems credentials. Creating the environment alone does not restrict publication. Configure required maintainer approval and deployment branches to control who approves publication.

Your branch rules must permit release commits and tags to be pushed; see branch permissions. Dispatching starts a publishing run; when required reviewers are configured, the release job waits for approval from a designated maintainer. Run your project's tests and build checks, review the changes, and dispatch from your default branch:

First release: Pass the numeric RubyGems account ID shown on the Pending Trusted Publishers page as rubygems-owner. This declares the account that will own the gem on its first publication. Replace YOUR_ACCOUNT_ID below with that ID:

gh workflow run release.yml -f rubygems-owner=YOUR_ACCOUNT_ID

Subsequent releases: Omit rubygems-owner once the gem exists. Its trusted publisher is still required, but the account ID is no longer needed:

gh workflow run release.yml

To release a different version, select it in the dispatch form or pass -f version=1.2.3. The standard workflow updates the configured version file before preparing the changelog, then starts the next development iteration from the selected release version.

For a real-world example of adding release automation to an existing gem, see ruby-link-checker #26. It adds the dependency, Rake tasks, reusable workflow, and release instructions while preserving the existing changelog format.

Replace only what you need. The standard workflow preserves ordering; Detailed Usage provides file examples and complete manual callbacks.

• Project conventions: Choose version objects and changelog formats, including custom implementations.
• Release decisions and callbacks: Customize validation, preparation, publication, and notifications. Callbacks receive an execution context with release data, step history, and the configured workflow.
• Semantic releases: Opt into Conventional Commits, release-history-based versions, and generated notes without changing the execution platform or registry.
• Packages and registries: Override package construction or supply a registry destination independently of hosted releases.
• Release hosting: Replace or disable GitHub Release creation without changing package publication or Git operations.
• Execution platforms: Supply an execution provider for environment transport, metadata, temporary storage, and authentication services. GitHub Actions is the only built-in external platform; another platform needs its own adapter and pipeline.
• Actions integration: Override commands, inputs, and timezone through the Actions Reference, or use the Composite Action inside a caller-owned job.

Execution platform, registry, and hosting are independent choices.

For complete examples, see releasing ruby-gem-release itself with small project-specific customizations, then GitLab and semantic releases for built-in semantic providers composed with placeholder GitLab adapters.

The defaults retain clean-checkout checks, duplicate-version checks, and verified recovery artifacts. Custom publication callbacks must preserve the documented ordering and artifact checks.

See UPGRADING.md for breaking changes and migration steps. Upgrade the gem and pinned workflow or action together.

See CONTRIBUTING.md, DESIGN.md, CHANGELOG.md, and RELEASING.md.

Distributed under the MIT License.