Skip to content

Commit 855eadd

Browse files
Use native provenance to attest the gem and release receipt. (#6)
1 parent 24e2bf4 commit 855eadd

10 files changed

Lines changed: 115 additions & 37 deletions

File tree

‎.github/releasing.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,6 @@ Merging a version increase publishes the actual merged commit through `release-p
88

99
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 downloaded before another upload is attempted. Do not 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.
1010

11-
Verify downloaded gems with `gh attestation verify FILE --repo OWNER/REPOSITORY --source-digest MERGED_SHA --signer-workflow OWNER/REPOSITORY/.github/workflows/release-publish.yaml`. Release assets include the gem, RubyGems Sigstore bundle, GitHub provenance bundle, and source/digest receipt.
11+
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.
1212

1313
The initial implementation supports public repositories, a single gemspec, stable patch/minor/major versions, and merge/squash commits. Keep rebase merges and merge queues disabled. Generation hooks must be repeatable from the same source and version. Run setup and account recovery checks before enabling publishing; see the companion gem's setup guide.

‎.github/workflows/release-publish.yaml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -73,14 +73,14 @@ jobs:
7373
env:
7474
PACKAGE: ${{ steps.build.outputs.package }}
7575
run: gem exec sigstore-cli:0.2.3 sign "$PACKAGE" --bundle "$PACKAGE.sigstore.json"
76-
- name: Attest exact source and artifact
76+
- name: Attest gem and release receipt
7777
if: steps.build.outputs.restored != 'true'
7878
id: attest
7979
uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4
8080
with:
81-
subject-path: ${{ steps.build.outputs.package }}
82-
predicate-type: https://slsa.dev/provenance/v1
83-
predicate-path: pkg/provenance.json
81+
subject-path: |
82+
${{ steps.build.outputs.package }}
83+
pkg/release.json
8484
- name: Retain provenance bundle
8585
if: steps.build.outputs.restored != 'true'
8686
env:

‎context/getting-started.md‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -60,23 +60,32 @@ If regeneration fails, prepare a new branch from the current default branch and
6060
After merge/squash, the publishing workflow verifies GitHub's merged PR record and ancestry, then checks out the exact merged commit. Later development on the default branch is allowed. It regenerates against the merged commit's **first parent**, builds in a clean worktree, optionally certificate-signs, and creates two attestations over the final bytes:
6161

6262
- A Sigstore bundle submitted explicitly with `gem push --attestation` using RubyGems 4.0.21.
63-
- GitHub SLSA provenance naming the exact checked-out commit, including when the workflow's own default-branch revision is newer.
63+
- GitHub's native SLSA provenance covering both the gem and `release.json`. This signed receipt binds the gem digest to the exact release commit, even when the workflow's own default-branch revision is newer.
6464

6565
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.
6666

6767
``` bash
68-
gh attestation verify example-1.2.3.gem \
69-
--repo OWNER/REPOSITORY \
70-
--source-digest MERGED_SHA \
71-
--signer-workflow OWNER/REPOSITORY/.github/workflows/release-publish.yaml
68+
set -e
69+
for file in example-1.2.3.gem release.json; do
70+
gh attestation verify "$file" \
71+
--repo OWNER/REPOSITORY --bundle provenance.sigstore.json \
72+
--cert-identity https://github.com/OWNER/REPOSITORY/.github/workflows/release-publish.yaml@refs/heads/main \
73+
--source-ref refs/heads/main --deny-self-hosted-runners
74+
done
75+
76+
jq -e --arg commit MERGED_SHA \
77+
--arg digest "$(shasum -a 256 example-1.2.3.gem | cut -d ' ' -f1)" \
78+
'.commit == $commit and .sha256 == $digest' release.json
7279

7380
gem exec sigstore-cli:0.2.3 verify example-1.2.3.gem \
7481
--bundle example-1.2.3.gem.sigstore.json \
7582
--certificate-identity https://github.com/OWNER/REPOSITORY/.github/workflows/release-publish.yaml@refs/heads/main \
7683
--certificate-oidc-issuer https://token.actions.githubusercontent.com
7784
```
7885

79-
Native GitHub records the merge and any bypass; the artifact receipt includes the PR and merging actor. This version does not export organization audit-log evidence or infer bypass reasons from review counts.
86+
Download `release.json` and `provenance.sigstore.json` alongside the gem. Verify both subjects before reading the receipt's source commit and digest. GitHub CLI's `--source-digest` checks the workflow revision, which may differ from the release commit recorded in the signed receipt. Replace `main` with the configured default branch in these commands.
87+
88+
Native GitHub records the merge and any bypass; the signed artifact receipt includes the PR and merging actor. This version does not export organization audit-log evidence or infer bypass reasons from review counts.
8089

8190
## Recovery
8291

‎guides/getting-started/readme.md‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -60,23 +60,32 @@ If regeneration fails, prepare a new branch from the current default branch and
6060
After merge/squash, the publishing workflow verifies GitHub's merged PR record and ancestry, then checks out the exact merged commit. Later development on the default branch is allowed. It regenerates against the merged commit's **first parent**, builds in a clean worktree, optionally certificate-signs, and creates two attestations over the final bytes:
6161

6262
- A Sigstore bundle submitted explicitly with `gem push --attestation` using RubyGems 4.0.21.
63-
- GitHub SLSA provenance naming the exact checked-out commit, including when the workflow's own default-branch revision is newer.
63+
- GitHub's native SLSA provenance covering both the gem and `release.json`. This signed receipt binds the gem digest to the exact release commit, even when the workflow's own default-branch revision is newer.
6464

6565
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.
6666

6767
``` bash
68-
gh attestation verify example-1.2.3.gem \
69-
--repo OWNER/REPOSITORY \
70-
--source-digest MERGED_SHA \
71-
--signer-workflow OWNER/REPOSITORY/.github/workflows/release-publish.yaml
68+
set -e
69+
for file in example-1.2.3.gem release.json; do
70+
gh attestation verify "$file" \
71+
--repo OWNER/REPOSITORY --bundle provenance.sigstore.json \
72+
--cert-identity https://github.com/OWNER/REPOSITORY/.github/workflows/release-publish.yaml@refs/heads/main \
73+
--source-ref refs/heads/main --deny-self-hosted-runners
74+
done
75+
76+
jq -e --arg commit MERGED_SHA \
77+
--arg digest "$(shasum -a 256 example-1.2.3.gem | cut -d ' ' -f1)" \
78+
'.commit == $commit and .sha256 == $digest' release.json
7279

7380
gem exec sigstore-cli:0.2.3 verify example-1.2.3.gem \
7481
--bundle example-1.2.3.gem.sigstore.json \
7582
--certificate-identity https://github.com/OWNER/REPOSITORY/.github/workflows/release-publish.yaml@refs/heads/main \
7683
--certificate-oidc-issuer https://token.actions.githubusercontent.com
7784
```
7885

79-
Native GitHub records the merge and any bypass; the artifact receipt includes the PR and merging actor. This version does not export organization audit-log evidence or infer bypass reasons from review counts.
86+
Download `release.json` and `provenance.sigstore.json` alongside the gem. Verify both subjects before reading the receipt's source commit and digest. GitHub CLI's `--source-digest` checks the workflow revision, which may differ from the release commit recorded in the signed receipt. Replace `main` with the configured default branch in these commands.
87+
88+
Native GitHub records the merge and any bypass; the signed artifact receipt includes the PR and merging actor. This version does not export organization audit-log evidence or infer bypass reasons from review counts.
8089

8190
## Recovery
8291

‎lib/bake/gem/github/publisher.rb‎

Lines changed: 9 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,6 @@ def build(number)
4040
raise "Unexpected package filename." unless File.basename(package) == filename
4141
receipt = evidence.merge(file: filename, sha256: Digest::SHA256.file(package).hexdigest, run_id: run, signing: @config.fetch("signing"))
4242
File.write(File.join(path, "release.json"), JSON.pretty_generate(receipt) + "\n")
43-
File.write(File.join(path, "provenance.json"), JSON.pretty_generate(provenance(receipt)) + "\n")
4443
output(receipt, restored: false)
4544
end
4645

@@ -60,7 +59,7 @@ def publish(number)
6059
bundle = "#{package}.sigstore.json"
6160
identity = "https://github.com/#{@repository}/.github/workflows/release-publish.yaml@refs/heads/#{@config.fetch('branch')}"
6261
gem_command("exec", "sigstore-cli:0.2.3", "verify", package, "--bundle", bundle, "--certificate-identity", identity, "--certificate-oidc-issuer", "https://token.actions.githubusercontent.com")
63-
system("gh", "attestation", "verify", package, "--repo", @repository, "--bundle", File.join(@root, "pkg", "provenance.sigstore.json"), "--signer-workflow", "#{@repository}/.github/workflows/release-publish.yaml", "--source-digest", receipt.fetch(:commit), "--deny-self-hosted-runners", chdir: @root)
62+
verify_provenance(package)
6463
tag = "v#{receipt.fetch(:version)}"
6564
guard_tag(tag, receipt.fetch(:commit))
6665
remote_digest = registry_digest(receipt.fetch(:name), receipt.fetch(:version))
@@ -90,7 +89,7 @@ def publish(number)
9089
end
9190
# Existing immutable assets are checked before upload; never clobber them.
9291
assets = api("releases/tags/#{tag}").fetch("assets")
93-
[package, bundle, File.join(@root, "pkg", "release.json"), File.join(@root, "pkg", "provenance.json"), File.join(@root, "pkg", "provenance.sigstore.json")].each do |file|
92+
[package, bundle, File.join(@root, "pkg", "release.json"), File.join(@root, "pkg", "provenance.sigstore.json")].each do |file|
9493
if existing = assets.find{|asset| asset.fetch("name") == File.basename(file)}
9594
digest = existing.fetch("digest")
9695
raise "Existing release asset differs: #{file}" unless digest == "sha256:#{Digest::SHA256.file(file).hexdigest}"
@@ -181,16 +180,13 @@ def output(receipt, restored:)
181180
receipt
182181
end
183182

184-
def provenance(receipt)
185-
{
186-
buildDefinition: {
187-
buildType: "https://actions.github.io/buildtypes/workflow/v1",
188-
externalParameters: {workflow: {ref: "refs/heads/#{@config.fetch('branch')}", repository: "https://github.com/#{@repository}", path: ".github/workflows/release-publish.yaml"}},
189-
internalParameters: {github: {event_name: ENV.fetch("GITHUB_EVENT_NAME"), repository_id: ENV.fetch("GITHUB_REPOSITORY_ID"), repository_owner_id: ENV.fetch("GITHUB_REPOSITORY_OWNER_ID")}},
190-
resolvedDependencies: [{uri: "git+https://github.com/#{@repository}@refs/heads/#{@config.fetch('branch')}", digest: {gitCommit: receipt.fetch(:commit)}}]
191-
},
192-
runDetails: {builder: {id: "https://github.com/actions/runner/github-hosted"}, metadata: {invocationId: "https://github.com/#{@repository}/actions/runs/#{ENV.fetch('GITHUB_RUN_ID')}/attempts/#{ENV.fetch('GITHUB_RUN_ATTEMPT')}"}}
193-
}
183+
def verify_provenance(package)
184+
ref = "refs/heads/#{@config.fetch('branch')}"
185+
identity = "https://github.com/#{@repository}/.github/workflows/release-publish.yaml@#{ref}"
186+
# The signed receipt binds the package digest to the release commit, independently of the workflow revision.
187+
[package, File.join(@root, "pkg", "release.json")].each do |file|
188+
system("gh", "attestation", "verify", file, "--repo", @repository, "--bundle", File.join(@root, "pkg", "provenance.sigstore.json"), "--cert-identity", identity, "--source-ref", ref, "--deny-self-hosted-runners", chdir: @root)
189+
end
194190
end
195191

196192
def registry_digest(name, version)

‎templates/release-publish.yaml.erb‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -75,14 +75,14 @@ jobs:
7575
env:
7676
PACKAGE: ${{ steps.build.outputs.package }}
7777
run: gem exec sigstore-cli:0.2.3 sign "$PACKAGE" --bundle "$PACKAGE.sigstore.json"
78-
- name: Attest exact source and artifact
78+
- name: Attest gem and release receipt
7979
if: steps.build.outputs.restored != 'true'
8080
id: attest
8181
uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4
8282
with:
83-
subject-path: ${{ steps.build.outputs.package }}
84-
predicate-type: https://slsa.dev/provenance/v1
85-
predicate-path: pkg/provenance.json
83+
subject-path: |
84+
${{ steps.build.outputs.package }}
85+
pkg/release.json
8686
- name: Retain provenance bundle
8787
if: steps.build.outputs.restored != 'true'
8888
env:

‎templates/releasing.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,6 @@ Merging a version increase publishes the actual merged commit through `release-p
88

99
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 downloaded before another upload is attempted. Do not 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.
1010

11-
Verify downloaded gems with `gh attestation verify FILE --repo OWNER/REPOSITORY --source-digest MERGED_SHA --signer-workflow OWNER/REPOSITORY/.github/workflows/release-publish.yaml`. Release assets include the gem, RubyGems Sigstore bundle, GitHub provenance bundle, and source/digest receipt.
11+
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.
1212

1313
The initial implementation supports public repositories, a single gemspec, stable patch/minor/major versions, and merge/squash commits. Keep rebase merges and merge queues disabled. Generation hooks must be repeatable from the same source and version. Run setup and account recovery checks before enabling publishing; see the companion gem's setup guide.

‎test/provenance.rb‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# frozen_string_literal: true
2+
3+
# Released under the MIT License.
4+
# Copyright, 2026, by Samuel Williams.
5+
6+
require_relative "../lib/bake/gem/github/publisher"
7+
8+
describe Bake::Gem::GitHub::Publisher do
9+
with "#verify_provenance" do
10+
let(:publisher) do
11+
instance = subject.allocate
12+
instance.instance_variable_set(:@root, "/release")
13+
instance.instance_variable_set(:@repository, "socketry/example")
14+
instance.instance_variable_set(:@config, {"branch" => "main"})
15+
instance
16+
end
17+
18+
it "verifies both package and receipt with the exact publishing identity" do
19+
commands = []
20+
mock(publisher) do |wrapper|
21+
wrapper.replace(:system) do |*arguments, **options|
22+
commands << [arguments, options]
23+
true
24+
end
25+
end
26+
publisher.send(:verify_provenance, "/release/pkg/example.gem")
27+
28+
options = [
29+
"--repo", "socketry/example", "--bundle", "/release/pkg/provenance.sigstore.json",
30+
"--cert-identity", "https://github.com/socketry/example/.github/workflows/release-publish.yaml@refs/heads/main",
31+
"--source-ref", "refs/heads/main", "--deny-self-hosted-runners"
32+
]
33+
expect(commands).to be == [
34+
[["gh", "attestation", "verify", "/release/pkg/example.gem", *options], {chdir: "/release"}],
35+
[["gh", "attestation", "verify", "/release/pkg/release.json", *options], {chdir: "/release"}]
36+
]
37+
end
38+
end
39+
end

‎test/recovery.rb‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
# A simulated registry and GitHub finalizer. Core content validation has its own
1010
# real-repository integration tests; this fixture exercises interruption/retry.
1111
class RecoveryPublisher < Bake::Gem::GitHub::Publisher
12-
attr_accessor :remote_digest, :fail_release, :fail_attestation
12+
attr_accessor :remote_digest, :fail_release, :fail_attestation, :fail_receipt_verification
1313
attr_reader :commands
1414

1515
def initialize(root)
@@ -31,6 +31,9 @@ def merged(number)
3131
def system(*arguments, **options)
3232
@commands << arguments
3333
raise "Attestation verification failed" if @fail_attestation && arguments[0, 3] == ["gem", "exec", "sigstore-cli:0.2.3"]
34+
if @fail_receipt_verification && arguments[0, 3] == ["gh", "attestation", "verify"] && arguments[3].end_with?("/release.json")
35+
raise "Receipt attestation verification failed"
36+
end
3437
if arguments[0, 2] == ["gem", "push"]
3538
@remote_digest = load_receipt.fetch(:sha256)
3639
end
@@ -70,7 +73,6 @@ def around
7073
FileUtils.mkdir_p(File.join(root, "pkg"))
7174
File.write(File.join(root, "pkg", "example-1.0.1.gem"), "Exact signed bytes")
7275
File.write(File.join(root, "pkg", "example-1.0.1.gem.sigstore.json"), JSON.generate(mediaType: "test"))
73-
File.write(File.join(root, "pkg", "provenance.json"), "{}")
7476
File.write(File.join(root, "pkg", "provenance.sigstore.json"), "{}")
7577
receipt = {name: "example", version: "1.0.1", file: "example-1.0.1.gem", sha256: Digest::SHA256.hexdigest("Exact signed bytes"), commit: "a" * 40, repository: "socketry/example", pull_request: 42, pull_request_url: "https://github.com/socketry/example/pull/42"}
7678
File.write(File.join(root, "pkg", "release.json"), JSON.generate(receipt))
@@ -102,4 +104,20 @@ def around
102104
expect{@publisher.publish(42)}.to raise_exception(RuntimeError, message: be =~ /different bytes/)
103105
expect(@publisher.commands.any?{|args| args[0, 3] == ["gh", "release", "create"]}).to be == false
104106
end
107+
108+
it "stops before publication when the receipt attestation is invalid" do
109+
@publisher.fail_receipt_verification = true
110+
expect{@publisher.publish(42)}.to raise_exception(RuntimeError, message: be =~ /Receipt attestation/)
111+
expect(@publisher.remote_digest).to be_nil
112+
expect(@publisher.commands.any?{|args| args[0, 2] == ["gem", "push"]}).to be == false
113+
end
114+
115+
it "rejects a receipt identifying another merged source" do
116+
path = File.join(@root, "pkg", "release.json")
117+
receipt = JSON.parse(File.read(path))
118+
receipt["commit"] = "b" * 40
119+
File.write(path, JSON.generate(receipt))
120+
expect{@publisher.publish(42)}.to raise_exception(RuntimeError, message: be =~ /not for this merged PR/)
121+
expect(@publisher.commands).to be == []
122+
end
105123
end

‎test/setup.rb‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,4 +65,11 @@ def generate
6565
expect{generate}.to raise_exception(RuntimeError, message: be =~ /Existing files differ/)
6666
expect(File.read(path)).to be == "Custom workflow\n"
6767
end
68+
69+
it "attests both the gem and its source receipt with native provenance" do
70+
generate
71+
workflow = YAML.safe_load_file(File.join(@root, ".github/workflows/release-publish.yaml"))
72+
attest = workflow.fetch("jobs").fetch("publish").fetch("steps").find{|step| step["id"] == "attest"}
73+
expect(attest.fetch("with")).to be == {"subject-path" => "${{ steps.build.outputs.package }}\npkg/release.json\n"}
74+
end
6875
end

0 commit comments

Comments
 (0)