Include versioned release notes in GitHub release descriptions.

Author: samuel-williams-shopify

bake-gem-github.gemspec

@@ -14,6 +14,7 @@ Gem::Specification.new do |spec|
 	spec.files = Dir.glob(["{bake,context,lib,templates}/**/*", "*.md", "release.cert"], base: __dir__)
 	spec.required_ruby_version = ">= 3.3"
 	spec.add_dependency "bake-gem", ">= 0.15.0"
+	spec.add_dependency "bake-releases", "~> 0.6"
 	spec.add_dependency "net-http"
 	spec.add_dependency "bake", "~> 0.25"
 end

context/getting-started.md

@@ -75,6 +75,8 @@ After merge/squash, the publishing workflow verifies GitHub's merged PR record a
 
 The workflow retains the gem, receipt and attestations before obtaining RubyGems publishing credentials. It verifies both attestations, checks the uploaded bytes and registry bundle, then pushes the specific version tag and creates the GitHub release. Existing tags/assets are checked and never overwritten. The old `after_gem_release` GitHub hook is not called by this pipeline, so there is one owner for release creation.
 
+The draft release description includes the exact version's notes from `releases.md` in the merged release checkout, followed by the PR URL, source commit, and gem digest. Notes are extracted using `bake-releases`; a missing or empty section leaves the metadata as the description. Retries preserve the existing release description.
+
 ``` bash
 set -e
 for file in example-1.2.3.gem release.json; do

gems.rb

@@ -15,6 +15,5 @@
 
 group :maintenance, optional: true do
 	gem "agent-context"
-	gem "bake-releases"
 	gem "utopia-project"
 end

guides/getting-started/readme.md

@@ -75,6 +75,8 @@ After merge/squash, the publishing workflow verifies GitHub's merged PR record a
 
 The workflow retains the gem, receipt and attestations before obtaining RubyGems publishing credentials. It verifies both attestations, checks the uploaded bytes and registry bundle, then pushes the specific version tag and creates the GitHub release. Existing tags/assets are checked and never overwritten. The old `after_gem_release` GitHub hook is not called by this pipeline, so there is one owner for release creation.
 
+The draft release description includes the exact version's notes from `releases.md` in the merged release checkout, followed by the PR URL, source commit, and gem digest. Notes are extracted using `bake-releases`; a missing or empty section leaves the metadata as the description. Retries preserve the existing release description.
+
 ``` bash
 set -e
 for file in example-1.2.3.gem release.json; do

lib/bake/gem/github/publisher.rb

@@ -4,6 +4,7 @@
 # Copyright, 2026, by Samuel Williams.
 
 require_relative "project"
+require "bake/releases"
 require "digest"
 require "net/http"
 require "openssl"
@@ -146,10 +147,12 @@ def preserve_release(receipt)
 					tag = "v#{receipt.fetch(:version)}"
 					release = github_release(tag)
 					unless release
+						notes = Bake::Releases.notes(tag, path: File.join(@root, "releases.md"))
+						metadata = "#{receipt.fetch(:pull_request_url)}\n\nSource: #{receipt.fetch(:commit)}\nSHA256: #{receipt.fetch(:sha256)}\n"
 						Tempfile.create("release") do |file|
 							file.write(JSON.generate(
 								tag_name: tag, draft: true, target_commitish: receipt.fetch(:commit), name: "#{receipt.fetch(:name)} #{tag}",
-								body: "#{receipt.fetch(:pull_request_url)}\n\nSource: #{receipt.fetch(:commit)}\nSHA256: #{receipt.fetch(:sha256)}\n\nSee releases.md at the release tag for release notes.\n"
+								body: [notes, metadata].compact.join("\n")
 							))
 							file.flush
 							# The release list can remain stale after a successful creation:

releases.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+  - Include the version's release notes in GitHub releases using `bake-releases`.
   - Update generated release files in the working tree with `gem:github:setup:update`.
 
 ## v0.0.5

test/bake/gem/github/publisher/recovery.rb

@@ -29,6 +29,74 @@ def restore
 		Bake::Context.load(root).call("gem:github:release:build", "number=42")
 	end
 
+	it "includes notes for the exact released version before the artifact metadata" do
+		File.write(File.join(root, "releases.md"), <<~MARKDOWN)
+			# Releases
+			
+			## Unreleased
+			
+			Future changes.
+			
+			## v2.0.0
+			
+			Newer release.
+			
+			## v1.0.1
+			
+			  - Fixed a `bug`.
+			
+			### Details
+			
+			Read the [guide](https://example.com/guide).
+			
+			## v1.0.0
+			
+			Older release.
+		MARKDOWN
+		
+		receipt = @publisher.publish(42)
+		
+		expect(@publisher.releases.first.fetch("body")).to be == <<~MARKDOWN
+			  - Fixed a `bug`.
+			
+			## Details
+			
+			Read the [guide](https://example.com/guide).
+			
+			https://github.com/socketry/example/pull/42
+			
+			Source: #{receipt.fetch(:commit)}
+			SHA256: #{receipt.fetch(:sha256)}
+		MARKDOWN
+	end
+	
+	it "uses the artifact metadata when release notes are missing" do
+		receipt = @publisher.publish(42)
+		
+		expect(@publisher.releases.first.fetch("body")).to be == <<~MARKDOWN
+			https://github.com/socketry/example/pull/42
+			
+			Source: #{receipt.fetch(:commit)}
+			SHA256: #{receipt.fetch(:sha256)}
+		MARKDOWN
+	end
+	
+	it "preserves the existing draft description when finalization is retried" do
+		File.write(File.join(root, "releases.md"), "## v1.0.1\n\nOriginal notes.\n")
+		@publisher.fail_release = true
+		expect{@publisher.publish(42)}.to raise_exception(RuntimeError, message: be =~ /GitHub unavailable/)
+		body = @publisher.releases.first.fetch("body") + "\nMaintainer addition.\n"
+		@publisher.releases.first["body"] = body
+		@publisher.fail_release = false
+		restore
+		
+		@publisher.publish(42)
+		
+		expect(@publisher.releases.size).to be == 1
+		expect(@publisher.releases.first.fetch("body")).to be == body
+		expect(@publisher.releases.first.fetch("draft")).to be == false
+	end
+	
 	it "resumes finalization after upload without uploading or rebuilding again" do
 		@publisher.fail_release = true
 		expect{@publisher.publish(42)}.to raise_exception(RuntimeError, message: be =~ /GitHub unavailable/)