ruby-gem-release 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1babfa3cbf929529a6e8d82e20d3caff5a890c65169dd9db841421e1b2e64057
-  data.tar.gz: 90a8b9b0f759a590d3ca2282d02e84aea20c9edc145af3019ee824fc6f2a05c2
+  metadata.gz: c5bb3465b2672800174dc8160f4f3dea172fab317cd9c6698c5e9555838830d9
+  data.tar.gz: 2c5c68af968df8d0a2b834efa4a3dc15c197a0567848588e9c819a2e7218d0db
 SHA512:
-  metadata.gz: 110cdc78d668d1fe44efdff779514d26bbdc83a4d1905bbb920fa9d8edaed02f1bb683694170141714363177f20b73b515629badea8179708e86fe00a3e4bc2a
-  data.tar.gz: e48613def1a278613a88e99575552425c3d6b1e8a6674e4b5f08010489ae5a608e730b09e0e9e46600b9543028c72ebf101528d1b4032e916458057e517c5773
+  metadata.gz: 75c793e1f932297cee9148c38a8fa85d642861f8e5bf884ec1911842fed7fa8ea19067f61f5a7c98e08eb1efabf44902557261cb72383c8f09723393611e0355
+  data.tar.gz: c28d2ccd7ef2588003a20c23c8275bbf3d077c9ecfb2a8cd113fbcc4c45e568c714cdd11a419a492cd291e53dfd08486686ef87612e4ad50cc3051c5773bfdd7

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.5.0 (2026/11/10)
+
+- [#28](https://github.com/dblock/ruby-gem-release/pull/28): Add success callbacks and structured failure callbacks with captured Ruby exceptions to both Actions interfaces - [@dblock](https://github.com/dblock).
+- [#29](https://github.com/dblock/ruby-gem-release/pull/29): Add release validation callbacks and successful skipping for empty pending notes, rename the prepared-release test command input from `validate` to `test` (breaking change), and document migration in [UPGRADING.md](UPGRADING.md) - [@dblock](https://github.com/dblock).
+- [#30](https://github.com/dblock/ruby-gem-release/pull/30): Rename preparation and next development iteration callbacks and Rake tasks to `prepare` and `bump`, matching the Actions command inputs (breaking change) - [@dblock](https://github.com/dblock).
+- [#31](https://github.com/dblock/ruby-gem-release/pull/31): Pass provider-specific execution contexts to callbacks with step history, workflow access, run metadata, and next development version propagation; separate registry destinations from package construction with a RubyGems implementation (breaking change) - [@dblock](https://github.com/dblock).
+- [#32](https://github.com/dblock/ruby-gem-release/pull/32): Separate execution-platform services into a provider-neutral base and GitHub implementation, delegate environment and failure transport, and separate identity-token acquisition from the RubyGems exchange (breaking change) - [@dblock](https://github.com/dblock).
+- [#33](https://github.com/dblock/ruby-gem-release/pull/33): Verify provider-neutral releases across separate consumer processes without Actions variables, group consumer specs under `spec/integration/` with a `spec:integration` Rake task, and guide README readers from defaults to workflow extensions - [@dblock](https://github.com/dblock).
+- [#35](https://github.com/dblock/ruby-gem-release/pull/35): Add self-release and GitLab semantic-release customization walkthroughs with example-local placeholder providers - [@dblock](https://github.com/dblock).
+- [#36](https://github.com/dblock/ruby-gem-release/pull/36): Move authentication into publication through destination hooks, remove registry-specific YAML steps, and unify RubyGems exchanges with optional owner binding and environment-only credentials; custom publication commands must not rely on a generated credentials file (breaking change) - [@dblock](https://github.com/dblock).
+- [#38](https://github.com/dblock/ruby-gem-release/pull/38): Speed up release tests by separating focused orchestration coverage from real-process consumer smoke tests and avoiding duplicate source and installed integration runs in CI - [@dblock](https://github.com/dblock).
+- [#37](https://github.com/dblock/ruby-gem-release/pull/37): Add opt-in semantic releases with reachable-tag history, configurable Conventional Commits rules and versions, persisted immutable decisions, generated notes and changelog files, and optional development bumps - [@dblock](https://github.com/dblock).
+- [#39](https://github.com/dblock/ruby-gem-release/pull/39): Preserve configured packages during context capture, share workflow installation and coherent state snapshots, and streamline release and migration documentation - [@dblock](https://github.com/dblock).
+- [#40](https://github.com/dblock/ruby-gem-release/pull/40): Make release tasks independently idempotent with source-commit timestamps, checksum-verified publication, reusable Git refs, and replaceable hosted notes/assets; fail empty-release validation and remove the decision-output protocol (breaking change) - [@dblock](https://github.com/dblock).
+- [#41](https://github.com/dblock/ruby-gem-release/pull/41): Isolate release tests from inherited release context so this project's self-release can run its test suite - [@dblock](https://github.com/dblock).
+- [#42](https://github.com/dblock/ruby-gem-release/pull/42): Standardize environment names into consistent input, gemspec, source, release, and registry families, and rename `release.previous_version` and its constructor keyword to `gemspec_version` to distinguish the captured gemspec version from release history (breaking change) - [@dblock](https://github.com/dblock).
+- [#43](https://github.com/dblock/ruby-gem-release/pull/43): Remove unused output-writing, strict availability, and Git/hosting readback methods and legacy state support; report failures from one coherent state snapshot (breaking change) - [@dblock](https://github.com/dblock).
+- [#44](https://github.com/dblock/ruby-gem-release/pull/44): Share local commit, build, and tag preparation between artifact checkpoints and publication while preserving independent, idempotent publication - [@dblock](https://github.com/dblock).
+- [#45](https://github.com/dblock/ruby-gem-release/pull/45): Remove the unused state format version and validate only invocation-local analysis and next-version fields - [@dblock](https://github.com/dblock).
+- [#47](https://github.com/dblock/ruby-gem-release/pull/47): Remove obsolete step-output parsing, registry lookup instrumentation, package name access, and the unused release argument from Git branch checks; verify custom registry publication by archive identity instead of lookup counts (breaking change) - [@dblock](https://github.com/dblock).
+- [#46](https://github.com/dblock/ruby-gem-release/pull/46): Correct rerun and preparation-order documentation, remove obsolete migration notes from reference pages, and keep upgrade guidance in the migration guide - [@dblock](https://github.com/dblock).
+- [#48](https://github.com/dblock/ruby-gem-release/pull/48): Update this project's action and reusable workflow pins in every Markdown file under `docs/`, alongside README, to the released tag during the next development iteration - [@dblock](https://github.com/dblock).
+
 ## 0.4.0 (2026/11/08)
 
 - [#24](https://github.com/dblock/ruby-gem-release/pull/24): Reject empty release notes in both built-in changelog formats before writing release updates, ignoring placeholders, category headings, comments, and reference definitions - [@dblock](https://github.com/dblock).

data/README.md

@@ -6,18 +6,9 @@
 
 **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 iteration with one workflow dispatch. Choose your version and changelog formats; the standard workflow handles the release sequence.
+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.
 
-- **No stored RubyGems API key:** Authenticate with RubyGems Trusted Publishing using OpenID Connect (OIDC).
-- **Let collaborators request releases:** After one-time setup, collaborators with write access, including on personal repositories, can dispatch releases without repository admin access or their own RubyGems credentials. [Environment protection](RELEASING.md#maintainer-approved-publication) can require approval from a release maintainer before publication.
-- **Keep your conventions:** Use the standard workflow or compose Ruby objects and callbacks for custom releases.
-- **Choose the release version:** Release the checked-in version or [select a different version](docs/actions/release.md#release-version) when dispatching, without a separate version-bump commit.
-- **Catch release mistakes:** [Check for already published RubyGems versions](docs/package/ruby_gem.md#check-version), reject existing tags, and [require actual release notes](docs/changelog/base.md#release) in both built-in changelog formats.
-- **Keep dependency files out of release commits:** [Reject dirty checkouts after dependency installation](docs/source_control/git.md) and unexpected working tree or index changes after preparation, instead of staging unrelated files during publication.
-- **Build once and retain recovery files:** Publish the same verified gem artifact to RubyGems and attach it to the GitHub Release. Preserve available gem, checksum manifest, and Git recovery bundle files for [recovery after failures](docs/actions/release.md#recovery-artifacts).
-- **Use your release timezone:** [Configure release dates](docs/actions/release.md#timezone) with a named timezone such as `America/New_York`, including daylight saving changes; UTC is the default.
-
-Requires Ruby 3.3+, GitHub Actions, and RubyGems Trusted Publishing.
+The default setup below requires Ruby 3.3+, GitHub Actions, and RubyGems Trusted Publishing.
 
 ## Usage
 
@@ -35,7 +26,7 @@ RubyGemRelease::Workflow::RubyGem.new(
 ).install_tasks
 ```
 
-The standard workflow handles changelog updates, publication, and the next development iteration, selecting the gemspec and repository using unambiguous defaults. See [Detailed Usage](docs/usage.md) for file examples and custom release callbacks.
+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.
 
 ### 2. Add the Release Workflow
 
@@ -62,7 +53,7 @@ permissions:
 
 jobs:
   release:
-    uses: dblock/ruby-gem-release/.github/workflows/release.yml@v0.3.1
+    uses: dblock/ruby-gem-release/.github/workflows/release.yml@v0.4.0
     with:
       ruby-version: '3.3'
       version: ${{ inputs.version }}
@@ -79,6 +70,8 @@ gh api --method PUT repos/{owner}/{repo}/environments/release
 
 For a new gem, open the [pending trusted publishers page](https://rubygems.org/profile/oidc/pending_trusted_publishers). 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](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.
 
+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](RELEASING.md#maintainer-approved-publication) to control who approves publication.
+
 ### 4. Make a Release
 
 Your branch rules must permit release commits and tags to be pushed; see [branch permissions](RELEASING.md#one-time-setup). 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:
@@ -99,15 +92,27 @@ To release a different version, select it in the dispatch form or pass `-f versi
 
 For a real-world example of adding release automation to an existing gem, see [ruby-link-checker #26](https://github.com/dblock/ruby-link-checker/pull/26). It adds the dependency, Rake tasks, reusable workflow, and release instructions while preserving the existing changelog format.
 
-## Configuration
+## Extending the Workflow
+
+Replace only what you need. The [standard workflow](docs/workflow/ruby_gem.md) preserves ordering; [Detailed Usage](docs/usage.md) provides file examples and complete manual callbacks.
+
+- **Project conventions:** Choose [version objects](docs/usage.md#version-objects) and [changelog formats](docs/usage.md#changelog-objects), including custom implementations.
+- **Release decisions and callbacks:** Customize [validation, preparation, publication, and notifications](docs/tasks.md). Callbacks receive an [execution context](docs/execution_context.md) with release data, step history, and the configured workflow.
+- **Semantic releases:** Opt into [Conventional Commits, release-history-based versions, and generated notes](docs/workflow/semantic_ruby_gem.md) without changing the execution platform or registry.
+- **Packages and registries:** Override [package construction](docs/package/ruby_gem.md) or supply a [registry destination](docs/destination.md) independently of hosted releases.
+- **Release hosting:** Replace or disable [GitHub Release creation](docs/workflow/ruby_gem.md#hosting) without changing package publication or Git operations.
+- **Execution platforms:** Supply an [execution provider](docs/execution_provider.md) 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](docs/actions/release.md), or use the [Composite Action](docs/actions/action.md) inside a caller-owned job.
+
+Execution platform, registry, and hosting are independent choices.
 
-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.
+For complete examples, see [releasing ruby-gem-release itself](examples/self_release/README.md) with small project-specific customizations, then [GitLab and semantic releases](examples/gitlab_semantic_release/README.md) for built-in semantic providers composed with placeholder GitLab adapters.
 
-For step-based integration, see the [Composite Action](docs/actions/action.md).
+The defaults retain [clean-checkout checks](docs/source_control/git.md), [duplicate-version checks](docs/destination/ruby_gems.md#check-version), and [verified recovery artifacts](docs/actions/release.md#recovery-artifacts). Custom publication callbacks must preserve the documented ordering and artifact checks.
 
-### Release Access
+## Upgrading
 
-Creating the environment without protection rules does not restrict release access. For maintainer-only publication, configure **Settings → Environments → release** with required maintainer reviewers, self-review and administrator-bypass rules, and deployment branches restricted to `main` (or your actual default branch), as described in [Maintainer-Approved Publication](RELEASING.md#maintainer-approved-publication). Other repository writers can still dispatch, but publication waits for a designated maintainer to approve; environments do not provide a workflow-dispatch allow list.
+See [UPGRADING.md](UPGRADING.md) for breaking changes and migration steps. Upgrade the gem and pinned workflow or action together.
 
 ## Contributing
 

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

@@ -11,15 +11,39 @@ module RubyGemRelease
       end
 
       def release!(release)
+        validate_release(release.version, release.date)
+        return if released?(release.version)
+
         update_release(version: release.version, date: release.date)
       end
 
+      def released?(version)
+        validate_version(version)
+        return false unless File.file?(@path)
+
+        matches = heading_positions(File.read(@path), release_pattern(version))
+        raise ArgumentError, "duplicate release headings in #{@path}" if matches.size > 1
+
+        matches.one?
+      end
+
       def prepare_next!(release)
         update_next(version: release.next_version, released_version: release.version)
       end
 
+      def pending?
+        content = File.read(@path)
+        notes?(document(unreleased_notes(content, newline(content))))
+      end
+
       private
 
+      def unreleased_notes(content, separator)
+        position = heading(content, self.class::UNRELEASED)
+        section_end = section_end_position(content, position, heading_prefix(content, position).length)
+        content[line_end(content, position, separator)...section_end]
+      end
+
       def heading(content, pattern)
         matches = heading_positions(content, pattern)
         raise ArgumentError, "expected exactly one matching heading in #{@path}" unless matches.one?

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module RubyGemRelease
+  module Changelog
+    class Generated < Base
+      def release!(release)
+        check_generated_notes(release)
+        content = File.exist?(@path) ? File.read(@path) : "# Changelog\n"
+        separator = newline(content)
+        return verify_notes(content, release) if released?(release.version)
+
+        File.write(@path, insert_release(content, release, separator))
+      end
+
+      def prepare_next!(_release); end
+
+      private
+
+      def release_pattern(version)
+        /\A## #{Regexp.escape(version)}(?: |\z)/
+      end
+
+      def verify_notes(content, release)
+        position = heading(content, release_pattern(release.version))
+        finish = section_end_position(content, position, 2)
+        notes = content[line_end(content, position, newline(content))...finish].strip.gsub("\r\n", "\n")
+        raise ArgumentError, 'existing generated release notes differ' unless notes == release.notes.strip
+      end
+
+      def check_generated_notes(release)
+        validate_release(release.version, release.date)
+        raise ArgumentError, 'generated release notes are required' unless release.notes.is_a?(String)
+
+        check_notes(release.notes, release.version)
+      end
+
+      def insert_release(content, release, separator)
+        sections = heading_positions(content, /\A## /, max_level: 2)
+        position = sections.first || content.length
+        entry = "## #{release.version} (#{release.date.strftime('%Y/%m/%d')})\n\n#{release.notes.strip}\n\n".gsub("\n", separator)
+        prefix = content[...position].sub(/(?:\r?\n)*\z/, "#{separator}#{separator}")
+        prefix + entry + content[position..]
+      end
+    end
+  end
+end

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

@@ -15,6 +15,10 @@ module RubyGemRelease
 
       private
 
+      def unreleased_notes(content, separator)
+        remove_placeholder(super, separator)
+      end
+
       def update_release(version:, date:)
         validate_release(version, date)
         content = File.read(@path)
@@ -36,23 +40,33 @@ module RubyGemRelease
         pattern = %r{\A\#{1,6} #{Regexp.escape(released_version)} \(\d{4}/\d{2}/\d{2}\)\z}
         position = heading(content, pattern)
         prefix = heading_prefix(content, position)
+        return if heading_positions(content, /\A\#{1,6} #{Regexp.escape(version)} \(Next\)\z/).one?
+
         check_absent(content, UNRELEASED, 'unreleased heading already exists')
 
         File.write(@path, content.insert(position, ["#{prefix} #{version} (Next)", '', @placeholder, '', ''].join(separator)))
       end
 
       def check_release_absent(content, version)
-        check_absent(content, %r{\A\#{1,6} #{Regexp.escape(version)} \(\d{4}/\d{2}/\d{2}\)\z}, 'release heading already exists')
+        check_absent(content, release_pattern(version), 'release heading already exists')
+      end
+
+      def release_pattern(version)
+        %r{\A\#{1,6} #{Regexp.escape(version)} \(\d{4}/\d{2}/\d{2}\)\z}
       end
 
       def release_notes(section, separator, version)
+        check_notes(remove_placeholder(section, separator), version)
+      end
+
+      def remove_placeholder(section, separator)
         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
         section.slice!(position, placeholder_length(section, position, separator))
-        check_notes(section, version)
+        section
       end
 
       def placeholder_length(section, position, separator)

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

@@ -7,6 +7,16 @@ module RubyGemRelease
 
       private
 
+      def release_pattern(version)
+        /\A\#{1,6} \[#{Regexp.escape(version)}\] - \d{4}-\d{2}-\d{2}\z/
+      end
+
+      def unreleased_notes(content, separator)
+        reference = unreleased_reference(content)
+        comparison(reference[2]) if reference
+        super
+      end
+
       def update_release(version:, date:)
         validate_release(version, date)
         content = File.read(@path)
@@ -24,11 +34,12 @@ module RubyGemRelease
         validate_version(released_version)
         content = File.read(@path)
         separator = newline(content)
-        pattern = /\A\#{1,6} \[#{Regexp.escape(released_version)}\] - \d{4}-\d{2}-\d{2}\z/
-        position = heading(content, pattern)
+        position = heading(content, release_pattern(released_version))
         prefix = heading_prefix(content, position)
-        check_absent(content, UNRELEASED, 'unreleased heading already exists')
         check_next_reference(content, released_version)
+        return if heading_positions(content, UNRELEASED).one?
+
+        check_absent(content, UNRELEASED, 'duplicate unreleased headings')
 
         File.write(@path, content.insert(position, ["#{prefix} [Unreleased]", '', ''].join(separator)))
       end

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

@@ -3,3 +3,4 @@
 require_relative 'changelog/base'
 require_relative 'changelog/intridea'
 require_relative 'changelog/keep_a_changelog'
+require_relative 'changelog/generated'

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'open3'
+require 'rubygems/package'
+require 'json'
+require 'digest'
+require_relative '../destination'
+require_relative '../workflow/ruby_gems_credentials'
+
+module RubyGemRelease
+  class Destination
+    class RubyGems < Destination
+      def authenticate!(provider:)
+        return unless provider.fetch('RELEASE_AUTH_MODE', '') == authentication
+
+        Workflow::RubyGemsCredentials.new(owner: provider.fetch('RUBYGEMS_OWNER_ID', ''), provider: provider).configure!
+      end
+
+      def authentication
+        'rubygems'
+      end
+
+      def publish!(release, package:)
+        path = package.artifact(release)
+        return if published?(release, package: package)
+
+        push(path, release: release, package: package)
+      end
+
+      def published?(release, package:)
+        path = package.artifact(release)
+        spec = Gem::Package.new(path).spec
+        raise 'Package version does not match release' unless spec.version.to_s == release.version
+
+        matching_publication?(spec, path)
+      end
+
+      private
+
+      def matching_publication?(spec, path)
+        response = version_response(spec.name, spec.version.to_s)
+        return false if response.code == '404'
+        raise "Cannot verify RubyGems publication (HTTP #{response.code})" unless response.code == '200'
+
+        metadata = JSON.parse(response.body)
+        checksum = metadata['sha'] if metadata.is_a?(Hash)
+        raise 'Published gem checksum differs or is unavailable; refusing to republish, see RELEASING.md for recovery' unless checksum == Digest::SHA256.file(path).hexdigest
+
+        true
+      end
+
+      def push(path, release:, package:)
+        output, error, status = Open3.capture3(Gem.ruby, '-S', 'gem', 'push', path)
+        raise "Destination command failed: #{error.strip}\n#{output.strip}" unless status.success? || published?(release, package: package)
+
+        output
+      end
+
+      def version_response(name, version)
+        uri = URI("https://rubygems.org/api/v2/rubygems/#{URI.encode_www_form_component(name)}/versions/#{URI.encode_www_form_component(version)}.json")
+        Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 30, max_retries: 0) { |http| http.get(uri.request_uri) }
+      rescue Timeout::Error, SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError => e
+        raise "Cannot check RubyGems for #{name} #{version}: #{e.message}; verify connectivity before retrying"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RubyGemRelease
+  class Destination
+    def authenticate!(provider:); end
+
+    def publish!(release, package:)
+      raise NotImplementedError, "#{self.class} must implement publish!"
+    end
+
+    def published?(_release, **)
+      raise ArgumentError, "#{self.class} must implement published? to verify recovery"
+    end
+
+    def authentication
+      nil
+    end
+  end
+end

data/lib/ruby-gem-release/execution_context/github/run.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative '../../execution_context'
+
+module RubyGemRelease
+  class ExecutionContext
+    class GitHub < ExecutionContext
+      class Run
+        attr_reader :repository, :ref, :sha, :run_id, :run_attempt, :job_id, :workflow_name, :workflow_ref
+
+        def initialize(environment: ENV)
+          @repository = value(environment, 'GITHUB_REPOSITORY')
+          @ref = value(environment, 'GITHUB_REF')
+          @sha = value(environment, 'GITHUB_SHA')
+          @run_id = value(environment, 'GITHUB_RUN_ID')
+          @run_attempt = value(environment, 'GITHUB_RUN_ATTEMPT')
+          @job_id = value(environment, 'GITHUB_JOB')
+          @workflow_name = value(environment, 'GITHUB_WORKFLOW')
+          @workflow_ref = value(environment, 'GITHUB_WORKFLOW_REF')
+          freeze
+        end
+
+        private
+
+        def value(environment, name)
+          environment[name]&.dup&.freeze
+        end
+      end
+    end
+  end
+end

data/lib/ruby-gem-release/execution_context/github/step.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative '../../execution_context'
+
+module RubyGemRelease
+  class ExecutionContext
+    class GitHub < ExecutionContext
+      class Step < ExecutionContext::Step
+        attr_reader :outcome, :conclusion
+
+        def initialize(id:, outcome: nil, conclusion: nil)
+          @outcome = status(outcome)
+          @conclusion = status(conclusion)
+          super(id: id)
+        end
+
+        private
+
+        def status(value)
+          return if value.nil?
+          raise ArgumentError, "invalid step status: #{value.inspect}" unless %w[success failure cancelled skipped].include?(value)
+
+          value.dup.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../execution_context'
+require_relative 'github/step'
+require_relative 'github/run'
+
+module RubyGemRelease
+  class ExecutionContext
+    class GitHub < ExecutionContext
+      def self.step_id(task, environment: ENV)
+        environment.fetch('RELEASE_STEP_ID', task)
+      end
+
+      def self.steps(environment: ENV)
+        attributes = JSON.parse(environment.fetch('RELEASE_STEPS_JSON', '{}'))
+        raise ArgumentError, 'release steps must be an object' unless attributes.is_a?(Hash)
+
+        attributes.to_h do |id, values|
+          raise ArgumentError, 'release step must be an object' unless values.is_a?(Hash)
+
+          [id.freeze, Step.new(id: id, outcome: values['outcome'], conclusion: values['conclusion'])]
+        end.freeze
+      end
+
+      def initialize(release:, task:, state:, workflow: nil, environment: ENV, analysis: state&.analysis)
+        super(release: release, task: task, state: state, workflow: workflow, analysis: analysis,
+              step: Step.new(id: self.class.step_id(task, environment: environment)),
+              steps: self.class.steps(environment: environment), run: Run.new(environment: environment))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module RubyGemRelease
+  class ExecutionContext
+    class Step
+      attr_reader :id
+
+      def initialize(id:)
+        raise ArgumentError, 'step ID must be a nonempty string' unless id.is_a?(String) && !id.empty?
+
+        @id = id.dup.freeze
+        freeze
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'execution_context/step'
+
+module RubyGemRelease
+  class ExecutionContext
+    attr_reader :release, :step, :steps, :workflow, :run, :analysis
+
+    def self.step_id(task)
+      task
+    end
+
+    def initialize(release:, task:, state:, workflow: nil, step: Step.new(id: task), steps: {}, run: nil, analysis: state&.analysis)
+      @release = release
+      @workflow = workflow
+      @state = state
+      @step = step
+      @steps = steps.dup.freeze
+      @run = run
+      @analysis = analysis
+      freeze
+    end
+
+    def record_next_version!(version)
+      @state.record_next_version!(version)
+    end
+
+    def record_analysis!(decision)
+      @state.record_analysis!(decision)
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+require_relative '../execution_provider'
+require_relative '../execution_context/github'
+
+module RubyGemRelease
+  class ExecutionProvider
+    class GitHub < ExecutionProvider
+      def directory
+        value = fetch('RUNNER_TEMP', nil)
+        value unless value.to_s.empty?
+      end
+
+      def ref
+        fetch('GITHUB_REF')
+      end
+
+      def git_identity
+        { name: fetch('GIT_USER_NAME', 'github-actions[bot]'), email: fetch('GIT_USER_EMAIL', 'github-actions[bot]@users.noreply.github.com') }
+      end
+
+      def export(values)
+        append_file('GITHUB_ENV', values)
+        super
+      end
+
+      def context(**attributes)
+        ExecutionContext::GitHub.new(**attributes, environment: @environment)
+      end
+
+      def step_id(task)
+        ExecutionContext::GitHub.step_id(task, environment: @environment)
+      end
+
+      def failed_steps
+        ExecutionContext::GitHub.steps(environment: @environment).select { |_id, step| step.outcome == 'failure' }.keys
+      end
+
+      def oidc_token(audience:)
+        body = oidc_response(oidc_request(audience))
+        token = body['value'] if body.is_a?(Hash)
+        raise 'OIDC response did not contain a valid token' unless token.is_a?(String) && !token.empty? && !token.match?(/[\r\n]/)
+
+        token
+      end
+
+      def mask(value)
+        puts "::add-mask::#{value.gsub('%', '%25').gsub("\r", '%0D').gsub("\n", '%0A')}"
+      end
+
+      private
+
+      def append_file(name, values)
+        validate_values(values)
+        File.open(fetch(name), 'a') { |file| values.each { |key, value| file.puts "#{key}=#{value}" } }
+      end
+
+      def oidc_request(audience)
+        uri = URI(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' }
+        uri.query = URI.encode_www_form(query + [['audience', audience]])
+        Net::HTTP::Get.new(uri).tap { |request| request['Authorization'] = "Bearer #{fetch('ACTIONS_ID_TOKEN_REQUEST_TOKEN')}" }
+      end
+
+      def oidc_response(request)
+        uri = request.uri
+        result = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 30, max_retries: 0) { |http| http.request(request) }
+        raise "OIDC request failed (HTTP #{result.code})" unless result.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(result.body)
+      rescue JSON::ParserError
+        raise 'OIDC response was not valid JSON'
+      end
+    end
+  end
+end