ruby-gem-release 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b08ae237496cfc6c20681b49de00754fa64855ca860d47f294cfc32db6a41bc6
+  data.tar.gz: de74d06f4cd776ae788843d29e6b9af1d5bb44cfd3db5a754cae007f895d8dd1
+SHA512:
+  metadata.gz: 3adf38a074fb0ecc9f260ee4ed1b5554b73e3b197b222e582fed079d4587fe82967e2bbad44979654d9bafa004a394990c378157cd6760c46c2602c250d7100a
+  data.tar.gz: 78cefbdc700cc788584fdbcbb9965e27afacd165d0b91452e133e858a7212eb2f3ca2a8f192c0f92d95d02edf454482dd3f43e29bd6e08d867611ba0c6ef48b5

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 (2026/11/07)
+
+- [#2](https://github.com/dblock/ruby-gem-release/pull/2): Add reusable gem release workflow and version management Rake tasks - [@dblock](https://github.com/dblock).
+- [#5](https://github.com/dblock/ruby-gem-release/pull/5): Add a ruby release logo - [@dblock](https://github.com/dblock).
+- [#6](https://github.com/dblock/ruby-gem-release/pull/6): Add release callbacks for project-specific changelog updates - [@dblock](https://github.com/dblock).
+- [#8](https://github.com/dblock/ruby-gem-release/pull/8): Add modular version and changelog updates, including comparison reference links, with a shared release context - [@dblock](https://github.com/dblock).
+- [#9](https://github.com/dblock/ruby-gem-release/pull/9): Add package, Git, and GitHub Release classes with dry-run-aware publication callbacks, environment-based lifecycle tasks, configurable workflow commands, and Git commit identity inputs - [@dblock](https://github.com/dblock).
+- [#10](https://github.com/dblock/ruby-gem-release/pull/10): Organize release classes, documentation, and tests by area; consolidate README configuration and add a reusable workflow reference - [@dblock](https://github.com/dblock).
+- [#11](https://github.com/dblock/ruby-gem-release/pull/11): Add a standard Ruby gem workflow with explicit strategies and configurable objects, and move manual callback usage into detailed documentation - [@dblock](https://github.com/dblock).
+- [#12](https://github.com/dblock/ruby-gem-release/pull/12): Explain release automation benefits and requirements, clarify version incrementing, simplify the caller example, and move configuration details out of README - [@dblock](https://github.com/dblock).
+- [#13](https://github.com/dblock/ruby-gem-release/pull/13): Add a manual project release caller using the standard workflow, with dry runs enabled by default - [@dblock](https://github.com/dblock).
+- [#14](https://github.com/dblock/ruby-gem-release/pull/14): Support owner-bound OIDC exchanges for first gem publication with pending trusted publishers - [@dblock](https://github.com/dblock).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Doubrovkine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,100 @@
+<img src="assets/logo.png" alt="A ruby gemstone launching like a rocket" width="160">
+
+# Ruby Gem Release
+
+[![Test](https://github.com/dblock/ruby-gem-release/actions/workflows/test.yml/badge.svg)](https://github.com/dblock/ruby-gem-release/actions/workflows/test.yml) [![Coverage Status](https://coveralls.io/repos/github/dblock/ruby-gem-release/badge.svg?branch=master)](https://coveralls.io/github/dblock/ruby-gem-release?branch=master)
+
+**Release your Ruby gem from GitHub Actions—without maintaining custom release scripts or storing a RubyGems API key.**
+
+Update your changelog, validate and publish your gem, create its GitHub Release, and prepare the next development version with one workflow dispatch. Choose your version and changelog formats; the standard workflow handles the release sequence.
+
+- **No stored RubyGems API key:** Authenticate with RubyGems Trusted Publishing using OpenID Connect (OIDC).
+- **Try it before publishing:** Dry runs exercise local commits, builds, and tags without uploading or pushing.
+- **Keep your conventions:** Use the standard workflow or compose Ruby objects and callbacks for custom releases.
+
+Requires Ruby 3.3+, GitHub Actions, and RubyGems Trusted Publishing.
+
+## Usage
+
+### 1. Configure Your Gem
+
+Add `ruby-gem-release` to the development dependencies and install the standard workflow in your Rakefile. Choose your version file and changelog format explicitly:
+
+```ruby
+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
+```
+
+The standard workflow handles changelog updates, publication, and the next development version, selecting the gemspec and repository using unambiguous defaults. See [Detailed Usage](docs/usage.md) for file examples and custom release callbacks.
+
+### 2. Add the Release Workflow
+
+Add `.github/workflows/release.yml` using the [sample workflow](examples/.github/workflows/release.yml), replacing the Ruby version with your project's value:
+
+```yaml
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      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@master
+    with:
+      ruby-version: '3.3'
+      rubygems-owner: ${{ inputs.rubygems-owner }}
+```
+
+### 3. Enable Trusted Publishing
+
+In your GitHub repository, open **Settings → Environments** and create an environment named `release`. Alternatively, from your repository directory, use `gh`:
+
+```sh
+gh api --method PUT repos/{owner}/{repo}/environments/release
+```
+
+On [RubyGems.org](https://rubygems.org), open your gem's **Trusted publishers** page and create a [trusted publisher](https://guides.rubygems.org/trusted-publishing/#using-reusable-workflows). 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. For a new gem, use the [pending trusted publishers page](https://rubygems.org/profile/oidc/pending_trusted_publishers) instead.
+
+For example, the trusted publishers page for a gem named `example` is `https://rubygems.org/gems/example/trusted_publishers`.
+
+### 4. Make a Release
+
+Your branch rules must permit release commits and tags to be pushed; see [branch permissions](RELEASING.md#one-time-setup). Review the changes and dispatch the workflow 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:
+
+```sh
+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:
+
+```sh
+gh workflow run release.yml
+```
+
+## Configuration
+
+See [Detailed Usage](docs/usage.md#configuration) for workflow customization, callbacks, and available classes, and the [Actions Reference](docs/actions/release.md) for inputs and defaults.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [DESIGN.md](DESIGN.md), [CHANGELOG.md](CHANGELOG.md), and [RELEASING.md](RELEASING.md).
+
+## License
+
+Distributed under the [MIT License](LICENSE.txt).

data/lib/ruby-gem-release/changelog/base.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'commonmarker'
+
+module RubyGemRelease
+  module Changelog
+    class Base
+      def initialize(path: 'CHANGELOG.md')
+        @path = path
+      end
+
+      def release!(release)
+        update_release(version: release.version, date: release.date)
+      end
+
+      def prepare_next!(release)
+        update_next(version: release.next_version, released_version: release.version)
+      end
+
+      private
+
+      def heading(content, pattern)
+        matches = heading_positions(content, pattern)
+        raise ArgumentError, "expected exactly one matching heading in #{@path}" unless matches.one?
+
+        matches.first
+      end
+
+      def heading_positions(content, pattern)
+        lines = content.lines
+        offsets = line_offsets(lines)
+        matches = []
+        document(content).each do |node|
+          next unless node.type == :heading && node.header_level == 2
+
+          index = node.source_position[:start_line] - 1
+          matches << offsets[index] if pattern.match?(lines[index].chomp)
+        end
+        matches
+      end
+
+      def editable_lines(content)
+        excluded = excluded_lines(content)
+        offset = 0
+        content.each_line.with_index(1) do |line, number|
+          yield line, offset unless excluded.include?(number)
+          offset += line.length
+        end
+      end
+
+      def document(content)
+        Commonmarker.parse(content, options: { extension: { shortcodes: false } })
+      end
+
+      def line_offsets(lines)
+        offset = 0
+        lines.map do |line|
+          position = offset
+          offset += line.length
+          position
+        end
+      end
+
+      def excluded_lines(content)
+        excluded = Set.new
+        document(content).walk do |node|
+          next unless %i[code_block html_block block_quote].include?(node.type)
+
+          position = node.source_position
+          excluded.merge(position[:start_line]..position[:end_line])
+        end
+        excluded
+      end
+
+      def newline(content)
+        raise ArgumentError, "mixed or unsupported line endings in #{@path}" if (content.match?(/(?<!\r)\n/) && content.include?("\r\n")) || content.match?(/\r(?!\n)/)
+
+        content.include?("\r\n") ? "\r\n" : "\n"
+      end
+
+      def validate_version(version)
+        raise ArgumentError, "invalid version: #{version.inspect}" unless version.is_a?(String) && /\A(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)\z/.match?(version)
+      end
+
+      def validate_release(version, date)
+        validate_version(version)
+        raise ArgumentError, 'date must be a Date' unless date.instance_of?(Date)
+      end
+
+      def check_absent(content, pattern, message)
+        raise ArgumentError, "#{message} in #{@path}" unless heading_positions(content, pattern).empty?
+      end
+    end
+  end
+end

data/lib/ruby-gem-release/changelog/intridea.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module RubyGemRelease
+  module Changelog
+    class Intridea < Base
+      UNRELEASED = /\A## \d+\.\d+\.\d+ \(Next\)\z/
+      PLACEHOLDER = '- Your contribution here.'
+
+      def initialize(path: 'CHANGELOG.md', placeholder: PLACEHOLDER)
+        raise ArgumentError, 'placeholder must be a single nonempty line' unless placeholder.is_a?(String) && !placeholder.empty? && !placeholder.match?(/[\r\n]/)
+
+        super(path: path)
+        @placeholder = placeholder
+      end
+
+      private
+
+      def update_release(version:, date:)
+        validate_release(version, date)
+        content = File.read(@path)
+        separator = newline(content)
+        position = heading(content, UNRELEASED)
+        check_release_absent(content, version)
+        line_end = line_end(content, position, separator)
+        section_end = heading_positions(content, /\A## /).find { |offset| offset > position } || content.length
+        content[position...section_end] = "## #{version} (#{date.strftime('%Y/%m/%d')})" +
+                                          remove_placeholder(content[line_end...section_end])
+        File.write(@path, content)
+      end
+
+      def update_next(version:, released_version:)
+        validate_version(version)
+        validate_version(released_version)
+        content = File.read(@path)
+        separator = newline(content)
+        pattern = %r{\A## #{Regexp.escape(released_version)} \(\d{4}/\d{2}/\d{2}\)\z}
+        position = heading(content, pattern)
+        check_absent(content, UNRELEASED, 'unreleased heading already exists')
+
+        File.write(@path, content.insert(position, ["## #{version} (Next)", '', @placeholder, '', ''].join(separator)))
+      end
+
+      def check_release_absent(content, version)
+        check_absent(content, %r{\A## #{Regexp.escape(version)} \(\d{4}/\d{2}/\d{2}\)\z}, 'release heading already exists')
+      end
+
+      def line_end(content, position, separator)
+        content.index(separator, position) || raise(ArgumentError, "heading must end with a newline in #{@path}")
+      end
+
+      def remove_placeholder(section)
+        positions = []
+        editable_lines(section) { |line, offset| positions << offset if line.chomp == @placeholder }
+        raise ArgumentError, "expected exactly one placeholder in #{@path}" unless positions.one?
+
+        position = positions.first
+        line_end = section.index("\n", position)
+        section.slice!(position, (line_end ? line_end + 1 : section.length) - position)
+        section
+      end
+    end
+  end
+end

data/lib/ruby-gem-release/changelog/keep_a_changelog.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module RubyGemRelease
+  module Changelog
+    class KeepAChangelog < Base
+      UNRELEASED = /\A## \[Unreleased\]\z/
+
+      private
+
+      def update_release(version:, date:)
+        validate_release(version, date)
+        content = File.read(@path)
+        separator = newline(content)
+        position = heading(content, UNRELEASED)
+        check_absent(content, /\A## \[#{Regexp.escape(version)}\] - \d{4}-\d{2}-\d{2}\z/, 'release heading already exists')
+        line_end = content.index(separator, position)
+        raise ArgumentError, "heading must end with a newline in #{@path}" unless line_end
+
+        content[position...line_end] = "## [#{version}] - #{date.strftime('%Y-%m-%d')}"
+        release_references(content, version, separator)
+        File.write(@path, content)
+      end
+
+      def update_next(version:, released_version:)
+        validate_version(version)
+        validate_version(released_version)
+        content = File.read(@path)
+        separator = newline(content)
+        pattern = /\A## \[#{Regexp.escape(released_version)}\] - \d{4}-\d{2}-\d{2}\z/
+        position = heading(content, pattern)
+        check_absent(content, UNRELEASED, 'unreleased heading already exists')
+        check_next_reference(content, released_version)
+
+        File.write(@path, content.insert(position, ['## [Unreleased]', '', ''].join(separator)))
+      end
+
+      def references(content, label)
+        return [] unless reference_defined?(content, label)
+
+        pattern = /\A[ \t]{0,3}\[#{Regexp.escape(label)}\]:[ \t]*(.*)\z/i
+        matches = []
+        editable_lines(content) do |line, offset|
+          match = pattern.match(line.chomp)
+          matches << [offset, line.chomp, match[1]] if match
+        end
+        matches
+      end
+
+      def reference_defined?(content, label)
+        node = document("#{content}\n\n[#{label}]\n").last_child.first_child
+        node&.type == :link
+      end
+
+      def unreleased_reference(content)
+        matches = references(content, 'Unreleased')
+        raise ArgumentError, 'duplicate Unreleased reference links' if matches.size > 1
+
+        matches.first
+      end
+
+      def comparison(url)
+        match = %r{\A(https?://[^\s<>]+/compare/)([^/\s]*?)(\d+\.\d+\.\d+)\.\.\.([^\s<>]+)\z}.match(url)
+        raise ArgumentError, 'Unreleased reference must be a comparison URL ending in VERSION...BRANCH' unless match
+
+        match
+      end
+
+      def release_references(content, version, separator)
+        reference = unreleased_reference(content)
+        return unless reference
+
+        raise ArgumentError, 'release reference already exists' unless references(content, version).empty?
+
+        offset, line, url = reference
+        match = comparison(url)
+        updated = "[Unreleased]: #{match[1]}#{match[2]}#{version}...#{match[4]}"
+        released = "[#{version}]: #{match[1]}#{match[2]}#{match[3]}...#{match[2]}#{version}"
+        content[offset, line.length] = "#{updated}#{separator}#{released}"
+      end
+
+      def check_next_reference(content, released_version)
+        reference = unreleased_reference(content)
+        return unless reference
+
+        match = comparison(reference[2])
+        raise ArgumentError, 'Unreleased comparison must start at the released version' unless match[3] == released_version
+      end
+    end
+  end
+end

data/lib/ruby-gem-release/changelog.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'changelog/base'
+require_relative 'changelog/intridea'
+require_relative 'changelog/keep_a_changelog'

data/lib/ruby-gem-release/hosting/github_release.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module RubyGemRelease
+  module Hosting
+    class GitHubRelease
+      def initialize(repository: nil)
+        repository ||= ENV.fetch('GITHUB_REPOSITORY', nil)
+        raise ArgumentError, 'repository must be OWNER/REPO' unless repository.nil? || (repository.is_a?(String) && %r{\A[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+\z}.match?(repository))
+
+        @repository = repository
+      end
+
+      def publish!(release, package: nil, artifacts: [])
+        version = release.version
+        raise ArgumentError, 'release version must be MAJOR.MINOR.PATCH' unless version.is_a?(String) && /\A(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)\z/.match?(version)
+
+        tag = "v#{version}"
+        paths = artifact_paths(package ? [package.artifact(release)] : artifacts)
+        return if release.dry_run?
+
+        output, error, status = Open3.capture3(*command(tag), *paths)
+        raise "GitHub Release creation failed: #{error.strip}" unless status.success?
+
+        output.strip
+      end
+
+      private
+
+      def command(tag)
+        arguments = ['gh', 'release', 'create', tag]
+        arguments.push('--repo', @repository) if @repository
+        arguments.push('--verify-tag', '--title', tag, '--generate-notes')
+      end
+
+      def artifact_paths(artifacts)
+        raise ArgumentError, 'artifacts must be an array of file paths' unless artifacts.is_a?(Array)
+
+        artifacts.map do |path|
+          raise ArgumentError, 'artifact must name an existing file without # or line breaks' unless path.is_a?(String) && !path.match?(/[#\r\n]/) && File.file?(path)
+
+          File.expand_path(path)
+        end
+      end
+    end
+  end
+end

data/lib/ruby-gem-release/package/ruby_gem.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'rubygems/package'
+require 'open3'
+require 'json'
+require 'digest'
+require 'fileutils'
+require 'tmpdir'
+
+module RubyGemRelease
+  module Package
+    class RubyGem
+      attr_reader :directory, :gemspec
+
+      def initialize(gemspec: nil, directory: nil)
+        @gemspec = resolve_gemspec(gemspec || ENV.fetch('GEMSPEC', nil))
+        @directory = directory || ENV['RUNNER_TEMP'] || Dir.mktmpdir('ruby-gem-release-')
+      end
+
+      def version
+        script = 'spec = Gem::Specification.load(ARGV.fetch(0)); abort "Cannot load gemspec" unless spec; puts spec.version'
+        run(Gem.ruby, '-rrubygems', '-e', script, @gemspec).strip
+      end
+
+      def build!(release)
+        FileUtils.mkdir_p(@directory)
+        run(Gem.ruby, '-S', 'gem', 'build', @gemspec, '--output', archive)
+        @manifest = build_manifest(release)
+        File.write(manifest_path, JSON.generate(@manifest))
+        artifact(release)
+      end
+
+      def artifact(release)
+        name = verified_manifest(release).fetch('name')
+        raise 'Invalid package name' unless /\A[A-Za-z0-9][A-Za-z0-9_.-]*\z/.match?(name)
+
+        path = File.join(@directory, "#{name}-#{release.version}.gem")
+        FileUtils.cp(archive, path)
+        path
+      end
+
+      def publish!(release)
+        path = artifact(release)
+        return path if release.dry_run?
+
+        run(Gem.ruby, '-S', 'gem', 'push', path)
+      end
+
+      private
+
+      def build_manifest(release)
+        spec = Gem::Package.new(archive).spec
+        raise "Built version #{spec.version} does not match #{release.version}" unless spec.version.to_s == release.version
+
+        { 'name' => spec.name, 'version' => spec.version.to_s, 'sha256' => Digest::SHA256.file(archive).hexdigest }
+      end
+
+      def verified_manifest(release)
+        manifest = @manifest || JSON.parse(File.read(manifest_path))
+        raise 'Package version does not match release' unless manifest.fetch('version') == release.version
+        raise 'Built artifact changed; refusing publication' unless Digest::SHA256.file(archive).hexdigest == manifest.fetch('sha256')
+
+        manifest
+      end
+
+      def archive
+        File.join(@directory, 'release.gem')
+      end
+
+      def manifest_path
+        File.join(@directory, 'release.json')
+      end
+
+      def resolve_gemspec(path)
+        paths = path.nil? || path.empty? ? Dir['*.gemspec'] : [path]
+        raise ArgumentError, 'Expected exactly one root gemspec; specify gemspec' unless paths.one?
+        raise ArgumentError, 'gemspec must name an existing file without line breaks' unless File.file?(paths.first) && !paths.first.match?(/[\r\n]/)
+
+        File.expand_path(paths.first)
+      end
+
+      def run(*command)
+        output, error, status = Open3.capture3(*command)
+        raise "Package command failed: #{error.strip}\n#{output.strip}" unless status.success?
+
+        output
+      end
+    end
+  end
+end

data/lib/ruby-gem-release/release.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module RubyGemRelease
+  class Release
+    attr_reader :version, :previous_version, :next_version, :date
+
+    def initialize(date:, version:, previous_version:, next_version: nil, dry_run: false)
+      raise ArgumentError, 'dry_run must be true or false' unless [true, false].include?(dry_run)
+
+      validate_versions(version, previous_version, next_version)
+      raise ArgumentError, 'date must be a Date' unless date.instance_of?(Date)
+
+      @version = version.dup.freeze
+      @previous_version = previous_version.dup.freeze
+      @next_version = next_version&.dup&.freeze
+      @date = date.dup.freeze
+      @dry_run = dry_run
+      freeze
+    end
+
+    def with_version(version)
+      self.class.new(version: version, previous_version: @previous_version, date: @date, next_version: @next_version, dry_run: @dry_run)
+    end
+
+    def with_next_version(version)
+      self.class.new(version: @version, previous_version: @previous_version, date: @date, next_version: version, dry_run: @dry_run)
+    end
+
+    def dry_run?
+      @dry_run
+    end
+
+    private
+
+    def validate_versions(version, previous_version, next_version)
+      raise ArgumentError, 'release versions must be strings' unless [version, previous_version].all?(String) && (next_version.nil? || next_version.is_a?(String))
+    end
+  end
+end

data/lib/ruby-gem-release/source_control/git.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'tmpdir'
+require 'fileutils'
+
+module RubyGemRelease
+  module SourceControl
+    class Git
+      def initialize(branch: nil, remote: 'origin', directory: nil)
+        @remote = remote
+        @branch = branch || ENV.fetch('DEFAULT_BRANCH', nil)
+        @directory = directory || ENV['RUNNER_TEMP'] || Dir.mktmpdir('ruby-gem-release-git-')
+      end
+
+      def configure!(name: 'github-actions[bot]', email: 'github-actions[bot]@users.noreply.github.com')
+        [name, email].each do |value|
+          raise ArgumentError, 'Git identity must be nonempty and contain no line breaks' unless value.is_a?(String) && !value.strip.empty? && !value.match?(/[\r\n]/)
+        end
+        run('config', '--local', 'user.name', name)
+        run('config', '--local', 'user.email', email)
+      end
+
+      def head
+        run('rev-parse', 'HEAD').strip
+      end
+
+      def check_tag!(version)
+        output, _error, status = Open3.capture3('git', 'show-ref', '--verify', '--quiet', "refs/tags/v#{version}")
+        raise "Release tag already exists: v#{version}" if status.success?
+        raise "Cannot check release tag: #{output}" unless status.exitstatus == 1
+      end
+
+      def check_current!(release, expected: head)
+        run('fetch', @remote, branch, '--tags')
+        return if release.dry_run?
+
+        raise 'Default branch advanced; start a new release' unless remote_head == expected
+      end
+
+      def commit!(release)
+        @release = release
+        @initial_commit = ENV['RELEASE_INITIAL_COMMIT'] || head
+        commit_changes("Prepare release #{release.version}", required: false)
+      end
+
+      def commit_next!(release)
+        @release = release
+        @next_commit_parent = head
+        commit_changes("Prepare next development version after #{release.version}", required: true)
+      end
+
+      def tag!(release)
+        @release = release
+        ensure_clean!
+        check_current!(release, expected: @initial_commit || ENV.fetch('RELEASE_INITIAL_COMMIT'))
+        check_tag!(release.version)
+        run('tag', "v#{release.version}")
+        FileUtils.mkdir_p(@directory)
+        run('bundle', 'create', File.join(@directory, 'release.bundle'), 'HEAD', "refs/tags/v#{release.version}")
+      end
+
+      def push!(release = @release)
+        raise ArgumentError, 'a release context is required before pushing' unless release
+        return if release.dry_run?
+
+        if @next_commit_parent
+          check_current!(release, expected: @next_commit_parent)
+          run('push', @remote, "HEAD:refs/heads/#{branch}")
+        else
+          check_current!(release, expected: @initial_commit || ENV.fetch('RELEASE_INITIAL_COMMIT'))
+          run('push', '--atomic', @remote, "HEAD:refs/heads/#{branch}", "refs/tags/v#{release.version}")
+        end
+      end
+
+      private
+
+      def branch
+        @branch ||= run('symbolic-ref', "refs/remotes/#{@remote}/HEAD").strip.delete_prefix("refs/remotes/#{@remote}/")
+      end
+
+      def remote_head
+        run('rev-parse', "refs/remotes/#{@remote}/#{branch}").strip
+      end
+
+      def ensure_clean!
+        raise 'Gem build changed the working tree after the release commit' unless run('status', '--porcelain', '--untracked-files=all').empty?
+      end
+
+      def commit_changes(message, required:)
+        run('add', '-A')
+        output = run('diff', '--cached', '--name-only')
+        raise 'Next-version preparation did not change any files' if required && output.empty?
+        return head if output.empty?
+
+        run('commit', '-m', message)
+        head
+      end
+
+      def run(*)
+        output, error, status = Open3.capture3('git', *)
+        raise "Git command failed: #{error.strip}\n#{output.strip}" unless status.success?
+
+        output
+      end
+    end
+  end
+end

data/lib/ruby-gem-release/tasks.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'rake'
+require_relative 'release'
+require_relative 'version/ruby_constant'
+require_relative 'workflow/context'
+require_relative 'workflow/ruby_gems_credentials'
+
+module RubyGemRelease
+  class Tasks
+    include Rake::DSL
+
+    def self.install
+      instance = new
+      yield instance if block_given?
+      instance.install
+    end
+
+    def install
+      namespace :release do
+        install_callback_tasks
+        install_publish_task
+        install_workflow_tasks
+      end
+    end
+
+    def before_release(&block)
+      raise ArgumentError, 'before_release requires a block' unless block
+      raise ArgumentError, 'before_release already configured' if @before_release
+
+      @before_release = block
+    end
+
+    def after_release(&block)
+      raise ArgumentError, 'after_release requires a block' unless block
+      raise ArgumentError, 'after_release already configured' if @after_release
+
+      @after_release = block
+    end
+
+    def publish(&block)
+      raise ArgumentError, 'publish requires a block' unless block
+      raise ArgumentError, 'publish already configured' if @publish
+
+      @publish = block
+    end
+
+    private
+
+    def install_workflow_tasks
+      namespace :workflow do
+        task(:capture) { Workflow::Context.new.capture! }
+        task(:resolve) { Workflow::Context.new.resolve! }
+        task(:credentials) { Workflow::RubyGemsCredentials.new(owner: ENV.fetch('RUBYGEMS_OWNER')).configure! }
+      end
+    end
+
+    def install_publish_task
+      desc 'Run the release publication callback'
+      task :publish do
+        @publish&.call(context)
+      end
+    end
+
+    def install_callback_tasks
+      desc 'Run the before-release callback'
+      task(:before_release) do
+        release = context(before_release: true)
+        @before_release&.call(release)
+      end
+      desc 'Run the next-version preparation callback'
+      task(:after_release) do
+        release = context
+        @after_release&.call(release)
+      end
+    end
+
+    def context(before_release: false)
+      previous_version = ENV.fetch('RELEASE_PREVIOUS_VERSION')
+      version = before_release ? previous_version : ENV.fetch('RELEASE_VERSION')
+      date = ENV.fetch('RELEASE_DATE')
+      validate_context_versions(version, previous_version)
+      raise ArgumentError, 'release date is required in YYYY-MM-DD format' unless date.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+
+      Release.new(version: version, previous_version: previous_version, date: Date.iso8601(date), dry_run: ENV.fetch('DRY_RUN', 'false') == 'true')
+    end
+
+    def validate_context_versions(*versions)
+      pattern = Version::RubyConstant::PATTERN
+      versions.compact.each do |value|
+        raise ArgumentError, "invalid version: #{value.inspect}; expected MAJOR.MINOR.PATCH" unless value.is_a?(String) && pattern.match?(value)
+      end
+    end
+  end
+end

data/lib/ruby-gem-release/version/ruby_constant.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubyGemRelease
+  module Version
+    class RubyConstant
+      PATTERN = /\A(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)\z/
+
+      def initialize(path:, constant:)
+        raise ArgumentError, 'constant must be a Ruby constant name' unless constant.is_a?(String) && /\A[A-Z]\w*\z/.match?(constant)
+
+        @path = path
+        @assignment = /^([ \t]*#{Regexp.escape(constant)}[ \t]*=[ \t]*)(['"])([^'"\r\n]+)\2/
+      end
+
+      def read
+        value = assignment(File.read(@path))[3]
+        parse(value)
+        value
+      end
+
+      def set(value)
+        parse(value)
+        content = File.read(@path)
+        match = assignment(content)
+        content[match.begin(3)...match.end(3)] = value
+        File.write(@path, content)
+        value
+      end
+
+      def increment!(part: :patch)
+        parts = parse(read)
+        index = { 'major' => 0, 'minor' => 1, 'patch' => 2 }.fetch(part.to_s) do
+          raise ArgumentError, 'bump part must be major, minor, or patch'
+        end
+        parts[index] += 1
+        ((index + 1)...parts.size).each { |i| parts[i] = 0 }
+        set(parts.join('.'))
+      end
+
+      private
+
+      def parse(value)
+        match = PATTERN.match(value) if value.is_a?(String)
+        raise ArgumentError, "invalid version: #{value.inspect}; expected MAJOR.MINOR.PATCH" unless match
+
+        match.captures.map(&:to_i)
+      end
+
+      def assignment(content)
+        matches = content.to_enum(:scan, @assignment).map { Regexp.last_match }
+        raise ArgumentError, "expected exactly one version assignment in #{@path}" unless matches.one?
+
+        matches.first
+      end
+    end
+  end
+end

data/lib/ruby-gem-release/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RubyGemRelease
+  VERSION = '0.1.0'
+end

data/lib/ruby-gem-release/workflow/context.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative '../package/ruby_gem'
+require_relative '../source_control/git'
+require_relative '../release'
+require_relative '../version/ruby_constant'
+
+module RubyGemRelease
+  module Workflow
+    class Context
+      def capture!
+        dry_run = ENV.fetch('DRY_RUN', 'false') == 'true'
+        check_branch(dry_run)
+        package = Package::RubyGem.new(gemspec: ENV.fetch('INPUT_GEMSPEC', nil))
+        release = initial_release(package, dry_run: dry_run)
+        git = configured_git
+        git.check_current!(release)
+        export('GEMSPEC' => package.gemspec, 'RELEASE_PREVIOUS_VERSION' => release.version,
+               'RELEASE_DATE' => release.date.iso8601, 'RELEASE_INITIAL_COMMIT' => git.head)
+      end
+
+      def resolve!
+        version = Package::RubyGem.new.version
+        validate_version(version)
+        expected = ENV.fetch('INPUT_VERSION', '')
+        raise "Prepared version #{version} does not match expected version #{expected}" unless expected.empty? || version == expected
+
+        SourceControl::Git.new.check_tag!(version)
+        export('RELEASE_VERSION' => version)
+      end
+
+      private
+
+      def initial_release(package, dry_run:)
+        version = package.version
+        validate_version(version)
+        validate_version(ENV.fetch('INPUT_VERSION')) unless ENV.fetch('INPUT_VERSION', '').empty?
+        Release.new(version: version, previous_version: version, date: Time.now.utc.to_date, dry_run: dry_run)
+      end
+
+      def configured_git
+        SourceControl::Git.new.tap do |git|
+          git.configure!(name: ENV.fetch('GIT_USER_NAME', 'github-actions[bot]'),
+                         email: ENV.fetch('GIT_USER_EMAIL', 'github-actions[bot]@users.noreply.github.com'))
+        end
+      end
+
+      def check_branch(dry_run)
+        return if dry_run
+        return if ENV.fetch('GITHUB_REF') == "refs/heads/#{ENV.fetch('DEFAULT_BRANCH')}"
+
+        raise 'Releases must run from the default branch'
+      end
+
+      def validate_version(version)
+        raise ArgumentError, 'Version must be MAJOR.MINOR.PATCH without leading zeros' unless Version::RubyConstant::PATTERN.match?(version)
+      end
+
+      def export(values)
+        File.open(ENV.fetch('GITHUB_ENV'), 'a') do |file|
+          values.each do |key, value|
+            raise ArgumentError, 'Workflow values cannot contain line breaks' if value.match?(/[\r\n]/)
+
+            file.puts "#{key}=#{value}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby-gem-release/workflow/ruby_gem.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative '../tasks'
+require_relative '../package/ruby_gem'
+require_relative '../source_control/git'
+require_relative '../hosting/github_release'
+
+module RubyGemRelease
+  module Workflow
+    class RubyGem
+      def initialize(version:, changelog:, package: Package::RubyGem.new, git: SourceControl::Git.new, hosting: Hosting::GitHubRelease.new)
+        @version = version
+        @changelog = changelog
+        @package = package
+        @git = git
+        @hosting = hosting
+      end
+
+      def install_tasks
+        Tasks.install do |tasks|
+          tasks.before_release { |release| prepare_release(release) }
+          tasks.publish { |release| publish(release) }
+          tasks.after_release { |release| prepare_next(release) }
+        end
+      end
+
+      private
+
+      def prepare_release(release)
+        @changelog&.release!(release.with_version(@version.read))
+      end
+
+      def publish(release)
+        @git.commit!(release)
+        @package.build!(release)
+        @git.tag!(release)
+        @package.publish!(release)
+        @git.push!(release)
+        @hosting&.publish!(release, package: @package)
+      end
+
+      def prepare_next(release)
+        next_release = release.with_next_version(@version.increment!)
+        @changelog&.prepare_next!(next_release)
+        @git.commit_next!(release)
+        @git.push!
+      end
+    end
+  end
+end

data/lib/ruby-gem-release/workflow/ruby_gems_credentials.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module RubyGemRelease
+  module Workflow
+    class RubyGemsCredentials
+      def initialize(owner:)
+        raise ArgumentError, 'RubyGems owner must be a positive numeric account ID' unless /\A[1-9]\d*\z/.match?(owner.to_s)
+
+        @owner = owner.to_s
+      end
+
+      def configure!
+        token = oidc_token
+        mask(token)
+        key = exchange_token(token)
+        mask(key)
+        File.open(ENV.fetch('GITHUB_ENV'), 'a') do |file|
+          %w[RUBYGEMS_API_KEY BUNDLE_GEM__PUSH_KEY GEM_HOST_API_KEY].each { |name| file.puts "#{name}=#{key}" }
+        end
+      end
+
+      private
+
+      def oidc_token
+        uri = URI(ENV.fetch('ACTIONS_ID_TOKEN_REQUEST_URL'))
+        raise ArgumentError, 'OIDC request URL must use HTTPS' unless uri.is_a?(URI::HTTPS)
+
+        query = URI.decode_www_form(uri.query || '').reject { |name, _value| name == 'audience' } # rubocop:disable Style/HashExcept -- Query pairs may contain duplicate keys.
+        uri.query = URI.encode_www_form(query + [['audience', 'rubygems.org']])
+        request = Net::HTTP::Get.new(uri)
+        request['Authorization'] = "Bearer #{ENV.fetch('ACTIONS_ID_TOKEN_REQUEST_TOKEN')}"
+        credential(response(uri, request), 'value')
+      end
+
+      def exchange_token(token)
+        uri = URI('https://rubygems.org/api/v1/oidc/trusted_publisher/exchange_token')
+        request = Net::HTTP::Post.new(uri)
+        request['Content-Type'] = 'application/json'
+        request['Accept'] = 'application/json'
+        request.body = JSON.generate(jwt: token, owner: @owner)
+        credential(response(uri, request), 'rubygems_api_key')
+      end
+
+      def response(uri, request)
+        result = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 30, max_retries: 0) do |http|
+          http.request(request)
+        end
+        raise "Credential request failed (HTTP #{result.code}); verify owner ID and pending trusted publisher" unless result.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(result.body)
+      rescue JSON::ParserError
+        raise 'Credential response was not valid JSON'
+      end
+
+      def credential(body, name)
+        value = body[name] if body.is_a?(Hash)
+        raise 'Credential response did not contain a valid token' unless value.is_a?(String) && !value.empty? && !value.match?(/[\r\n]/)
+
+        value
+      end
+
+      def mask(value)
+        puts "::add-mask::#{value.gsub('%', '%25')}"
+      end
+    end
+  end
+end

data/lib/ruby-gem-release.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'ruby-gem-release/version'
+require_relative 'ruby-gem-release/tasks'
+
+module RubyGemRelease
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: ruby-gem-release
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniel Doubrovkine
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: commonmarker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13'
+description: Reusable GitHub Actions workflow and Rake tasks for Ruby gem releases.
+email:
+- dblock@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/ruby-gem-release.rb
+- lib/ruby-gem-release/changelog.rb
+- lib/ruby-gem-release/changelog/base.rb
+- lib/ruby-gem-release/changelog/intridea.rb
+- lib/ruby-gem-release/changelog/keep_a_changelog.rb
+- lib/ruby-gem-release/hosting/github_release.rb
+- lib/ruby-gem-release/package/ruby_gem.rb
+- lib/ruby-gem-release/release.rb
+- lib/ruby-gem-release/source_control/git.rb
+- lib/ruby-gem-release/tasks.rb
+- lib/ruby-gem-release/version.rb
+- lib/ruby-gem-release/version/ruby_constant.rb
+- lib/ruby-gem-release/workflow/context.rb
+- lib/ruby-gem-release/workflow/ruby_gem.rb
+- lib/ruby-gem-release/workflow/ruby_gems_credentials.rb
+homepage: https://github.com/dblock/ruby-gem-release
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/dblock/ruby-gem-release/issues
+  changelog_uri: https://github.com/dblock/ruby-gem-release/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/dblock/ruby-gem-release
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Reusable release workflow and Rake tasks for Ruby gems.
+test_files: []