Preserve a complete archive before individual release asset uploads

Author: samuel-williams-shopify

.github/releasing.md

@@ -6,9 +6,9 @@ Review the entire release diff. Native GitHub rules require the configured revie
 
 Merging a version increase publishes the actual merged commit through `release-publish.yaml`. There is no second release approval. The public `release.cert` stays in Git; the optional private key belongs in the Actions secret `GEM_SIGNING_KEY`, supplied by the `rubygems` environment or an organization secret. RubyGems authentication uses Trusted Publishing.
 
-Before uploading to RubyGems, the publisher preserves the verified gem, receipt and both attestation bundles as assets of a draft GitHub release. The draft becomes public after registry verification and tag creation. Registry propagation is retried for up to one minute.
+Before uploading to RubyGems, the publisher uploads `release.tar` containing the verified gem, receipt and both attestation bundles to a draft GitHub release, then uploads their individual assets. The draft becomes public after registry verification and tag creation. Registry propagation is retried for up to one minute.
 
-If a publishing job fails, use **Re-run all jobs** on that same workflow run, or `bundle exec bake gem:github:release:resume run=RUN_ID`. The original artifact is restored from the workflow artifact or GitHub release before another upload is attempted. Actions artifacts can disappear on rerun, so the draft release is the durable backup. Do not delete it, create a replacement version bump or rebuild an already-published version. Conflicting bytes or tags require investigation; never automatically yank a version or move a tag. An incomplete draft requires restoring the missing original files before retrying.
+If a publishing job fails, use **Re-run all jobs** on that same workflow run, or `bundle exec bake gem:github:release:resume run=RUN_ID`. The original artifact is restored from the workflow artifact or GitHub release before another upload is attempted. Actions artifacts can disappear on rerun, so the draft release is the durable backup. Do not delete it, create a replacement version bump or rebuild an already-published version. Conflicting bytes or tags require investigation; never automatically yank a version or move a tag. A complete `release.tar` lets a rerun restore the original files and finish interrupted individual uploads. If neither the archive nor the Actions artifact completed, restore the missing original files before retrying. Existing backups and assets are checked and conflicting content is never overwritten.
 
 Verify both the downloaded gem and `release.json` with `gh attestation verify`, enforcing the publishing workflow's certificate identity and default branch ref. Then check the signed receipt's source commit and gem digest; follow the companion gem's setup guide for the complete commands. `--source-digest` checks the workflow revision, which can differ from the release commit. Release assets include the gem, RubyGems Sigstore bundle, GitHub provenance bundle, and signed source/digest receipt.
 

context/getting-started.md

@@ -106,7 +106,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

@@ -106,7 +106,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 "digest"
 require "net/http"
 require "openssl"
@@ -34,9 +35,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
@@ -158,16 +170,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

@@ -3,6 +3,7 @@
 ## Unreleased
 
   - 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
 

templates/releasing.md

@@ -6,9 +6,9 @@ Review the entire release diff. Native GitHub rules require the configured revie
 
 Merging a version increase publishes the actual merged commit through `release-publish.yaml`. There is no second release approval. The public `release.cert` stays in Git; the optional private key belongs in the Actions secret `GEM_SIGNING_KEY`, supplied by the `rubygems` environment or an organization secret. RubyGems authentication uses Trusted Publishing.
 
-Before uploading to RubyGems, the publisher preserves the verified gem, receipt and both attestation bundles as assets of a draft GitHub release. The draft becomes public after registry verification and tag creation. Registry propagation is retried for up to one minute.
+Before uploading to RubyGems, the publisher uploads `release.tar` containing the verified gem, receipt and both attestation bundles to a draft GitHub release, then uploads their individual assets. The draft becomes public after registry verification and tag creation. Registry propagation is retried for up to one minute.
 
-If a publishing job fails, use **Re-run all jobs** on that same workflow run, or `bundle exec bake gem:github:release:resume run=RUN_ID`. The original artifact is restored from the workflow artifact or GitHub release before another upload is attempted. Actions artifacts can disappear on rerun, so the draft release is the durable backup. Do not delete it, create a replacement version bump or rebuild an already-published version. Conflicting bytes or tags require investigation; never automatically yank a version or move a tag. An incomplete draft requires restoring the missing original files before retrying.
+If a publishing job fails, use **Re-run all jobs** on that same workflow run, or `bundle exec bake gem:github:release:resume run=RUN_ID`. The original artifact is restored from the workflow artifact or GitHub release before another upload is attempted. Actions artifacts can disappear on rerun, so the draft release is the durable backup. Do not delete it, create a replacement version bump or rebuild an already-published version. Conflicting bytes or tags require investigation; never automatically yank a version or move a tag. A complete `release.tar` lets a rerun restore the original files and finish interrupted individual uploads. If neither the archive nor the Actions artifact completed, restore the missing original files before retrying. Existing backups and assets are checked and conflicting content is never overwritten.
 
 Verify both the downloaded gem and `release.json` with `gh attestation verify`, enforcing the publishing workflow's certificate identity and default branch ref. Then check the signed receipt's source commit and gem digest; follow the companion gem's setup guide for the complete commands. `--source-digest` checks the workflow revision, which can differ from the release commit. Release assets include the gem, RubyGems Sigstore bundle, GitHub provenance bundle, and signed source/digest receipt.