Preserve a complete archive before individual release asset uploads

Author: samuel-williams-shopify

context/getting-started.md

@@ -110,7 +110,9 @@ bundle exec bake gem:github:release:resume run=RUN_ID
 
 Rerunning keeps the original event identity. A retained artifact is downloaded and its source identity/digest checked. A matching registry version resumes tag/release finalization; different bytes or a conflicting tag stop. There is no automatic yank, retag, or rebuild of an already-published version. Registry propagation is retried every ten seconds for up to one minute; a digest or attestation mismatch fails immediately.
 
-Before uploading to RubyGems, the publisher stores the verified gem, receipt and both attestation bundles in a draft GitHub release targeting the merged commit. It publishes the draft after registry verification and tag creation. Actions artifacts are also retained for 90 days, but can disappear on rerun. Recovery falls back to the draft or published release and verifies the original bytes and attestations. Keep the draft until finalization succeeds. If asset preservation was interrupted and neither backup is complete, restore the missing original files before retrying; conflicting assets are never overwritten.
+Before uploading to RubyGems, the publisher stores the verified gem, receipt and both attestation bundles together in `release.tar`, uploaded as one draft-release asset before their individual assets. The draft targets the merged commit. It publishes the draft after registry verification and tag creation. Actions artifacts are also retained for 90 days, but can disappear on rerun. Recovery falls back to `release.tar` in the draft or published release, checking its digest and requiring exactly the four expected regular files before restoring them. It verifies the original bytes and attestations, then resumes any missing individual asset uploads. Older releases without an archive can still restore their four individual assets. Existing assets and backups are compared with the original files and never replaced with conflicting content.
+
+A rerun can recover an interrupted individual asset upload once `release.tar` is available, even if the Actions artifact has disappeared. An available Actions artifact can also resume an interrupted archive upload. If neither backup completed, restore the missing original files manually; the publisher stops before uploading to RubyGems. Keep the draft until finalization succeeds. A published version is never rebuilt to fill a missing backup.
 
 GitHub concurrency does not guarantee a durable FIFO queue: rerun any publishing run displaced while pending. Resume reruns all jobs, including integrity checks; it does not repeat or second-guess the native review policy or a permitted administrator bypass. Older publishing runs execute their original code; adding this recovery support to the default branch does not change an already-triggered workflow.
 

fixtures/bake/gem/github/recovery_publisher.rb

@@ -12,7 +12,7 @@ module GitHub
 			# real-repository integration tests; this fixture exercises interruption/retry.
 			class RecoveryPublisher < Publisher
 				attr_accessor :remote_digest, :fail_release, :fail_attestation, :fail_receipt_verification
-				attr_accessor :releases, :artifacts, :fail_preservation, :stale_release_list
+				attr_accessor :releases, :artifacts, :fail_preservation, :stale_release_list, :fail_preservation_after
 				attr_reader :commands, :stored_files
 
 				def initialize(root)
@@ -45,13 +45,17 @@ def system(*arguments, **options)
 					end
 					case arguments[0, 3]
 					when ["gh", "release", "upload"]
-						raise "Preservation failed" if @fail_preservation
+						raise "Preservation failed" if @fail_preservation || (@fail_preservation_after && @stored_files.size >= @fail_preservation_after)
 						file = arguments[4]
 						@stored_files[File.basename(file)] = File.binread(file)
 						@releases.first.fetch("assets") << {"name" => File.basename(file), "digest" => "sha256:#{Digest::SHA256.file(file).hexdigest}"}
 					when ["gh", "release", "download"], ["gh", "run", "download"]
-						path = arguments[arguments.index("--dir") + 1]
-						@stored_files.each{|name, content| File.binwrite(File.join(path, name), content)}
+						if index = arguments.index("--output")
+							File.binwrite(arguments[index + 1], @stored_files.fetch("release.tar"))
+						else
+							path = arguments[arguments.index("--dir") + 1]
+							@stored_files.each{|name, content| File.binwrite(File.join(path, name), content)}
+						end
 					when ["gh", "release", "edit"]
 						raise "GitHub unavailable after upload" if @fail_release
 						@releases.first["draft"] = false

guides/getting-started/readme.md

@@ -110,7 +110,9 @@ bundle exec bake gem:github:release:resume run=RUN_ID
 
 Rerunning keeps the original event identity. A retained artifact is downloaded and its source identity/digest checked. A matching registry version resumes tag/release finalization; different bytes or a conflicting tag stop. There is no automatic yank, retag, or rebuild of an already-published version. Registry propagation is retried every ten seconds for up to one minute; a digest or attestation mismatch fails immediately.
 
-Before uploading to RubyGems, the publisher stores the verified gem, receipt and both attestation bundles in a draft GitHub release targeting the merged commit. It publishes the draft after registry verification and tag creation. Actions artifacts are also retained for 90 days, but can disappear on rerun. Recovery falls back to the draft or published release and verifies the original bytes and attestations. Keep the draft until finalization succeeds. If asset preservation was interrupted and neither backup is complete, restore the missing original files before retrying; conflicting assets are never overwritten.
+Before uploading to RubyGems, the publisher stores the verified gem, receipt and both attestation bundles together in `release.tar`, uploaded as one draft-release asset before their individual assets. The draft targets the merged commit. It publishes the draft after registry verification and tag creation. Actions artifacts are also retained for 90 days, but can disappear on rerun. Recovery falls back to `release.tar` in the draft or published release, checking its digest and requiring exactly the four expected regular files before restoring them. It verifies the original bytes and attestations, then resumes any missing individual asset uploads. Older releases without an archive can still restore their four individual assets. Existing assets and backups are compared with the original files and never replaced with conflicting content.
+
+A rerun can recover an interrupted individual asset upload once `release.tar` is available, even if the Actions artifact has disappeared. An available Actions artifact can also resume an interrupted archive upload. If neither backup completed, restore the missing original files manually; the publisher stops before uploading to RubyGems. Keep the draft until finalization succeeds. A published version is never rebuilt to fill a missing backup.
 
 GitHub concurrency does not guarantee a durable FIFO queue: rerun any publishing run displaced while pending. Resume reruns all jobs, including integrity checks; it does not repeat or second-guess the native review policy or a permitted administrator bypass. Older publishing runs execute their original code; adding this recovery support to the default branch does not change an already-triggered workflow.
 

lib/bake/gem/github/backup.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "rubygems/package"
+
+module Bake
+	module Gem
+		module GitHub
+			# Stores the original release files together so a single completed upload can recover them.
+			module Backup
+				# Write the release files to a tar archive.
+				def self.write(path, files)
+					File.open(path, "wb") do |output|
+						::Gem::Package::TarWriter.new(output) do |archive|
+							files.each do |file|
+								archive.add_file(File.basename(file), 0644){|entry| entry.write(File.binread(file))}
+							end
+						end
+					end
+				end
+				
+				# Read only the expected regular files; reject missing, duplicate, or unexpected entries before extraction.
+				def self.read(path, names)
+					files = {}
+					File.open(path, "rb") do |input|
+						::Gem::Package::TarReader.new(input) do |archive|
+							archive.each do |entry|
+								name = entry.full_name
+								raise "Unexpected release backup entry: #{name}" unless entry.file? && names.include?(name) && !files.key?(name)
+								files[name] = entry.read
+							end
+						end
+					end
+					raise "Release backup is incomplete." unless files.keys.sort == names.sort
+					files
+				end
+			end
+		end
+	end
+end

lib/bake/gem/github/publisher.rb

@@ -4,6 +4,7 @@
 # Copyright, 2026, by Samuel Williams.
 
 require_relative "project"
+require_relative "backup"
 require "bake/releases"
 require "digest"
 require "net/http"
@@ -35,9 +36,20 @@ def build(number)
 						guard_release(release, evidence.fetch(:commit))
 						filename = "#{evidence.fetch(:name)}-#{evidence.fetch(:version)}.gem"
 						files = release_files(file: filename)
-						names = release.fetch("assets").map{|asset| asset.fetch("name")}
-						raise "Retained release is incomplete; restore the original files before retrying." unless files.all?{|file| names.include?(File.basename(file))}
-						system("gh", "release", "download", release.fetch("tag_name"), "--repo", @repository, "--dir", path, *files.flat_map{|file| ["--pattern", File.basename(file)]}, chdir: @root)
+						if backup = release.fetch("assets").find{|asset| asset.fetch("name") == "release.tar"}
+							contents = read_backup(release, backup, files)
+							contents.each do |name, content|
+								file = File.join(path, name)
+								raise "Existing artifact differs: #{name}" if File.exist?(file) && File.binread(file) != content
+							end
+							contents.each do |name, content|
+								File.binwrite(File.join(path, name), content)
+							end
+						else
+							names = release.fetch("assets").map{|asset| asset.fetch("name")}
+							raise "Retained release is incomplete; restore the original files before retrying." unless files.all?{|file| names.include?(File.basename(file))}
+							system("gh", "release", "download", release.fetch("tag_name"), "--repo", @repository, "--dir", path, *files.flat_map{|file| ["--pattern", File.basename(file)]}, chdir: @root)
+						end
 					elsif retained
 						raise "Retained artifact expired and no GitHub release is available. Restore the original files before retrying."
 					else
@@ -161,16 +173,37 @@ def preserve_release(receipt)
 					end
 					guard_release(release, receipt.fetch(:commit))
 					assets = release.fetch("assets")
-					release_files(receipt).each do |file|
+					files = release_files(receipt)
+					files.each do |file|
 						if existing = assets.find{|asset| asset.fetch("name") == File.basename(file)}
 							raise "Existing release asset differs: #{file}" unless existing.fetch("digest") == "sha256:#{Digest::SHA256.file(file).hexdigest}"
-						else
+						end
+					end
+					if backup = assets.find{|asset| asset.fetch("name") == "release.tar"}
+						contents = read_backup(release, backup, files)
+						raise "Existing release backup differs." unless files.all?{|file| contents.fetch(File.basename(file)) == File.binread(file)}
+					else
+						# A complete backup needs only one successful upload, before individual assets:
+						backup = File.join(@root, "pkg/release.tar")
+						Backup.write(backup, files)
+						system("gh", "release", "upload", tag, backup, "--repo", @repository, chdir: @root)
+					end
+					files.each do |file|
+						unless assets.any?{|asset| asset.fetch("name") == File.basename(file)}
 							system("gh", "release", "upload", tag, file, "--repo", @repository, chdir: @root)
 						end
 					end
 					release
 				end
 
+				def read_backup(release, asset, files)
+					Tempfile.create("release-backup") do |file|
+						system("gh", "release", "download", release.fetch("tag_name"), "--repo", @repository, "--pattern", "release.tar", "--output", file.path, "--clobber", chdir: @root)
+						raise "Release backup digest mismatch." unless asset.fetch("digest") == "sha256:#{Digest::SHA256.file(file.path).hexdigest}"
+						Backup.read(file.path, files.map{|path| File.basename(path)})
+					end
+				end
+				
 				def verify_registry(receipt, bundle, attempts: 7, delay: 10)
 					local_bundle = JSON.parse(File.read(bundle))
 					attempts.times do |attempt|

releases.md

@@ -12,6 +12,7 @@
 
   - 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`.
+  - Preserve all release files in one archive before individual asset uploads, so reruns can recover interrupted drafts.
 
 ## v0.0.5
 

test/bake/gem/github/backup.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "bake/gem/github/backup"
+require "sus/fixtures/temporary_directory_context"
+
+describe Bake::Gem::GitHub::Backup do
+	include Sus::Fixtures::TemporaryDirectoryContext
+	
+	let(:path) {File.join(root, "release.tar")}
+	
+	it "preserves binary package bytes and the receipt together" do
+		files = {"example.gem" => "\x00\xffpackage".b, "release.json" => "{}"}
+		files.each{|name, content| File.binwrite(File.join(root, name), content)}
+		subject.write(path, files.keys.map{|name| File.join(root, name)})
+		expect(subject.read(path, files.keys)).to be == files
+	end
+	
+	it "rejects an incomplete backup" do
+		File.write(File.join(root, "example.gem"), "package")
+		subject.write(path, [File.join(root, "example.gem")])
+		expect{subject.read(path, ["example.gem", "release.json"])}.to raise_exception(RuntimeError, message: be =~ /incomplete/)
+	end
+	
+	[["../outside"], ["/absolute"], ["example.gem", "example.gem"]].each do |entries|
+		it "rejects unexpected or duplicate filenames", unique: entries do
+			File.open(path, "wb") do |file|
+				Gem::Package::TarWriter.new(file) do |archive|
+					entries.each{|name| archive.add_file(name, 0644){|entry| entry.write("bytes")}}
+				end
+			end
+			expect{subject.read(path, ["example.gem"])}.to raise_exception(RuntimeError, message: be =~ /Unexpected release backup entry/)
+		end
+	end
+	
+	it "rejects links in place of release files" do
+		File.open(path, "wb") do |file|
+			Gem::Package::TarWriter.new(file){|archive| archive.add_symlink("example.gem", "../outside", 0644)}
+		end
+		expect{subject.read(path, ["example.gem"])}.to raise_exception(RuntimeError, message: be =~ /Unexpected release backup entry/)
+	end
+end

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

@@ -121,6 +121,65 @@ def restore
 		expect(@publisher.remote_digest).to be_nil
 	end
 
+	it "recovers an interrupted individual asset upload without an Actions artifact" do
+		@publisher.fail_preservation_after = 2
+		expect{@publisher.publish(42)}.to raise_exception(RuntimeError, message: be =~ /Preservation failed/)
+		expect(@publisher.remote_digest).to be_nil
+		expect(@publisher.stored_files.keys).to be == ["release.tar", "example-1.0.1.gem"]
+		@publisher.fail_preservation_after = nil
+		receipt = restore
+		@publisher.publish(42)
+		expect(@publisher.remote_digest).to be == receipt.fetch(:sha256)
+		expect(@publisher.commands.count{|args| args[0, 3] == ["gh", "release", "upload"] && args[4].end_with?("release.tar")}).to be == 1
+		expect(@publisher.releases.first.fetch("draft")).to be == false
+	end
+	
+	it "resumes preservation from an available Actions artifact" do
+		originals = Dir.glob(File.join(root, "pkg/*")).to_h{|file| [File.basename(file), File.binread(file)]}
+		@publisher.fail_preservation = true
+		expect{@publisher.publish(42)}.to raise_exception(RuntimeError, message: be =~ /Preservation failed/)
+		@publisher.stored_files.merge!(originals)
+		@publisher.artifacts = [{"name" => "release-#{'a' * 40}", "expired" => false}]
+		@publisher.fail_preservation = false
+		restore
+		@publisher.publish(42)
+		expect(@publisher.releases.first.fetch("assets").size).to be == 5
+		expect(@publisher.remote_digest).to be == Digest::SHA256.hexdigest("Exact signed bytes")
+	end
+	
+	it "requires manual restoration if interrupted before either backup completed" do
+		@publisher.fail_preservation = true
+		expect{@publisher.publish(42)}.to raise_exception(RuntimeError, message: be =~ /Preservation failed/)
+		expect{restore}.to raise_exception(RuntimeError, message: be =~ /incomplete/)
+		expect(@publisher.remote_digest).to be_nil
+	end
+	
+	it "rejects a corrupted backup download" do
+		@publisher.publish(42)
+		@publisher.stored_files["release.tar"] = "corrupted"
+		expect{restore}.to raise_exception(RuntimeError, message: be =~ /backup digest mismatch/)
+	end
+	
+	it "does not overwrite conflicting local files while restoring a backup" do
+		@publisher.publish(42)
+		File.write(File.join(root, "pkg/release.json"), "Local content")
+		expect(ENV).to receive(:fetch).with("GITHUB_RUN_ID").and_return("123")
+		expect{@publisher.build(42)}.to raise_exception(RuntimeError, message: be =~ /Existing artifact differs/)
+		expect(File.read(File.join(root, "pkg/release.json"))).to be == "Local content"
+	end
+	
+	it "does not replace an existing backup containing different bytes" do
+		@publisher.publish(42)
+		package = File.join(root, "pkg/example-1.0.1.gem")
+		File.write(package, "Different package")
+		archive = File.join(root, "pkg/release.tar")
+		Bake::Gem::GitHub::Backup.write(archive, Dir.glob(File.join(root, "pkg/*")).reject{|file| file == archive})
+		@publisher.stored_files["release.tar"] = File.binread(archive)
+		@publisher.releases.first.fetch("assets").find{|asset| asset.fetch("name") == "release.tar"}["digest"] = "sha256:#{Digest::SHA256.file(archive).hexdigest}"
+		File.write(package, "Exact signed bytes")
+		expect{@publisher.publish(42)}.to raise_exception(RuntimeError, message: be =~ /Existing release backup differs/)
+	end
+	
 	it "restores expired workflow artifacts from the GitHub release" do
 		@publisher.publish(42)
 		@publisher.artifacts = [{"name" => "release-#{'a' * 40}", "expired" => true}]
@@ -166,12 +225,14 @@ def restore
 
 	it "requires a complete release backup before restoring" do
 		@publisher.publish(42)
+		@publisher.releases.first.fetch("assets").reject!{|asset| asset.fetch("name") == "release.tar"}
 		@publisher.releases.first.fetch("assets").pop
 		expect{restore}.to raise_exception(RuntimeError, message: be =~ /incomplete/)
 	end
 
 	it "rejects another source commit in the restored receipt" do
 		@publisher.publish(42)
+		@publisher.releases.first.fetch("assets").reject!{|asset| asset.fetch("name") == "release.tar"}
 		receipt = JSON.parse(@publisher.stored_files.fetch("release.json"))
 		receipt["commit"] = "b" * 40
 		@publisher.stored_files["release.json"] = JSON.generate(receipt)
@@ -192,9 +253,9 @@ def restore
 
 	it "does not overwrite conflicting release assets" do
 		@publisher.publish(42)
-		@publisher.releases.first.fetch("assets").first["digest"] = "sha256:wrong"
+		@publisher.releases.first.fetch("assets").find{|asset| asset.fetch("name").end_with?(".gem")}["digest"] = "sha256:wrong"
 		expect{@publisher.publish(42)}.to raise_exception(RuntimeError, message: be =~ /Existing release asset differs/)
-		expect(@publisher.commands.count{|args| args[0, 3] == ["gh", "release", "upload"]}).to be == 4
+		expect(@publisher.commands.count{|args| args[0, 3] == ["gh", "release", "upload"]}).to be == 5
 	end
 
 	it "uses the created draft response when the release list remains stale" do
@@ -203,7 +264,7 @@ def restore
 		expect(@publisher.releases.size).to be == 1
 		expect(@publisher.releases.first.fetch("draft")).to be == false
 		expect(@publisher.remote_digest).to be == receipt.fetch(:sha256)
-		expect(@publisher.stored_files.keys.sort).to be == ["example-1.0.1.gem", "example-1.0.1.gem.sigstore.json", "provenance.sigstore.json", "release.json"]
+		expect(@publisher.stored_files.keys.sort).to be == ["example-1.0.1.gem", "example-1.0.1.gem.sigstore.json", "provenance.sigstore.json", "release.json", "release.tar"]
 	end
 
 	it "restores an existing draft hidden by a stale release list without creating another" do