bake-gem-github 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbf4137a4b137fec26486a02e3941687f2c5fc9ded9ab95eb95619657892e1ae
-  data.tar.gz: c4e2cf0281e703e2d2264e5b8f08420ba7afeb5f7819e075a196e9334f24a300
+  metadata.gz: 4f7557669b8ec839c193fbf060816c360413ba4be3cd8e223f294acb8e29baed
+  data.tar.gz: c4806b56446c74082b785e6f19ac8a36cfbe1cd79a07ba05eda3bcd223ceaeb8
 SHA512:
-  metadata.gz: 2996e3c56f916e0d367c6fc75e3b7d9a478d8a08ee4d6d9bd775412978965c8c83d0b2608655d5d0c23776ce29af835cfa8dea4ec23ffb9e1afb3d0cefb74069
-  data.tar.gz: 4b78a2dd8d672b8831b8408e59494832ef45afee93489e9f27dc4aa7aae593f541350133886fa2f7957e2befee20abd4faa92b9df0b110620db78cdd1c1b2b01
+  metadata.gz: 522b233facca2afd17c28320ee34de988053bc33832a595c4e54ad34a308997813d54afaf43aa8a6c6b785b0a882b0f953aa5fecd7c4d004c0d4a21180d8f9b7
+  data.tar.gz: 7d4dbe694f2209d5a369c2e8100101a824b1cc0839023dd4a58976b9022154428c6e7e87ab8185b70f17e7913746f07bf4abdeabd4145c510ade5c3b8ba44ee3

data/bake/gem/github/release.rb

@@ -26,6 +26,14 @@ def major(refresh: false)
 	Bake::Gem::GitHub::Project.new(context.root).prepare(context, "major", refresh: refresh)
 end
 
+# Regenerate release content and require one release commit; ordinary PRs pass without a commit limit.
+# @parameter base [String] The current target commit.
+# @parameter candidate [String] The proposed PR head.
+# @returns [Hash | Nil] Release metadata, or nil for an ordinary PR.
+def validate(base:, candidate: "HEAD")
+	Bake::Gem::GitHub::Project.new(context.root).validate(base: base, candidate: candidate)
+end
+
 # Resolve and validate a pushed commit, emitting its merged PR and commit for publishing.
 # @parameter number [String | Nil] A merged PR number for older workflows; defaults to `RELEASE_PR`.
 # @parameter commit [String | Nil] The pushed commit SHA; defaults to `RELEASE_COMMIT` and takes precedence over `number`.

data/context/getting-started.md

@@ -6,7 +6,7 @@ This guide explains how to configure reviewed Ruby gem releases and prepare the
 
 Maintainers prepare a release PR containing the version bump and generated release notes. CI regenerates those changes from the current base to verify the content. Native GitHub rules control approval and merging. A push to the default branch starts release inspection; GitHub Actions builds the exact pushed commit only when it is a validated, merged release PR, then publishes its verified artifact to RubyGems.
 
-`bake-gem` provides version updates, release hooks, and clean builds. `bake-gem-github` adds PR preparation, GitHub policy, and remote publishing. The supported process uses one gemspec, stable three-part versions, merge or squash merging, and RubyGems.org.
+`bake-gem` provides version updates, release hooks, and clean builds. `bake-gem-github` adds PR preparation, GitHub policy, and remote publishing. The supported process uses one gemspec, stable three-part versions, single-commit release PRs, and RubyGems.org. Release PRs can be squash merged, rebase merged, or merged with a merge commit.
 
 ## Installation
 
@@ -69,10 +69,14 @@ reviewers:
 
 Replace `your-org/managers` with your organization and team slug, for example `socketry/managers`. Individual user logins are also supported. Reviewers need at least read access to the repository. Setup resolves their GitHub IDs without changing repository access or team membership.
 
+Reviewer teams must have **Visible** visibility in GitHub team settings. Plan and apply reject **Secret** teams before changing any settings, because GitHub can silently discard them from the environment reviewer list. Setup does not change team visibility.
+
 GitHub accepts one to six users or teams, and **one approval from any listed reviewer or team member is sufficient**. It does not support a minimum environment approval count. The default two PR approvals are independent of this publishing approval.
 
 Create the environment and restrict its deployment branch as described above before running plan or apply with reviewers configured. The plan previews the current and desired environment settings. Apply replaces its reviewer list while preserving its wait timer, self-review prevention, administrator bypass setting, and deployment branch restrictions. Custom deployment protection rules are managed separately and are not modified. Reapplying an identical reviewer list leaves the environment unchanged.
 
+After updating the environment, apply reads its settings back and fails if the reviewer identities or preserved protections differ from the requested configuration. Reviewer order does not matter. Earlier updates may already have completed; inspect the environment in GitHub and rerun `gem:github:setup:plan` before retrying apply.
+
 Omitting `reviewers` leaves environment settings unmanaged, including any existing reviewer requirement. An empty list is rejected. To remove an existing requirement, change the environment settings explicitly in GitHub.
 
 The RubyGems Trusted Publisher must explicitly require the `rubygems` environment; leaving that field blank would allow this trusted publisher to authenticate jobs without the environment approval. Keep administrator bypass enabled if administrators should be able to explicitly authorize publication without a reviewer. Environment approvals are available for public repositories on GitHub Free.
@@ -86,7 +90,9 @@ bundle exec bake gem:github:setup:plan
 bundle exec bake gem:github:setup:apply
 ```
 
-Apply updates the four managed rulesets and, when configured, the existing environment's reviewer list. It preserves unrelated rulesets. Other repository and organization protections still apply. Keep check names in `config/release.yaml` synchronized with the workflows, and apply updated rules after renamed jobs are available. Keep rebase merging and merge queues disabled for this process.
+Apply updates the four managed rulesets and, when configured, the existing environment's reviewer list. It preserves unrelated rulesets. Other repository and organization protections still apply. Keep check names in `config/release.yaml` synchronized with the workflows, and apply updated rules after renamed jobs are available.
+
+The generated rules allow merge, squash, and rebase methods; repository settings determine which are available. For linear history, enable squash and/or rebase merging and disable merge commits in repository settings. Release validation requires exactly one commit when the version changes; ordinary PRs have no commit limit. Keep merge queues disabled for this process.
 
 ## Prepare the first release PR
 
@@ -111,13 +117,15 @@ git diff
 
 This updates managed files in the working tree and returns their changed paths. Review the diff and selectively retain repository customizations before committing. The task does not stage, commit, or change remote settings. Repeated updates produce no further changes unless customizations differ from the templates. Apply changed rulesets after the corresponding workflows are running.
 
+To enable rebase merging on an existing installation, regenerate and merge `release-validate.yaml` so it runs `gem:github:release:validate`, which requires single-commit release PRs. Then review `gem:github:setup:plan` and run `gem:github:setup:apply` to allow rebase merging in the managed rules. Enable rebase merging in repository settings as well. Upgrading the gem alone does not update workflows or live rules.
+
 Regenerate existing workflows to adopt publishing on `push` instead of `pull_request_target`. The workflow filename and `rubygems` environment remain the same, so the RubyGems Trusted Publisher configuration does not change. No exception to GitHub's `pull_request_target` execution policy is needed. The resolve task continues to accept PR numbers from older workflows while you migrate.
 
 The release workflows follow `bake modernize` action versions and use moving major tags where available. The RubyGems credentials action uses its [documented `@main` reference](https://github.com/rubygems/configure-rubygems-credentials#trusted-publisher-recommended). Repositories that require fixed revisions can customize these references.
 
 ## Current scope
 
-The process has published `bake-gem-github` through GitHub Actions. Each adopting repository still needs its own reviewed setup and successful release. Public single-gem repositories, ordinary stable versions, merge/squash, GitHub-hosted Linux runners, and RubyGems.org are the supported starting point.
+The process has published `bake-gem-github` through GitHub Actions. Each adopting repository still needs its own reviewed setup and successful release. Public single-gem repositories, ordinary stable versions, single-commit release PRs using squash/rebase/merge, GitHub-hosted Linux runners, and RubyGems.org are the supported starting point.
 
 Native build matrices, reusable publisher workflows, merge queues, automated RubyGems ownership/MFA setup, cross-run artifact recovery, and organization-wide migration are outside the current setup tasks.
 

data/context/preparing-releases.md

@@ -19,11 +19,20 @@ gh workflow run release-prepare.yaml -f bump=patch
 
 Replace `patch` with `minor` or `major`. The wrapper fetches the default branch and tags, refuses a stale local checkout, and validates an existing release PR before returning its URL. A matching local or remote branch is reused if PR creation was interrupted. Multiple open release PRs or a different requested bump stop preparation. GitHub's built-in token may require a writer to approve running workflows for its created PR; enable Actions' permission to create PRs. An organization-owned App token can be adopted later if automatic CI triggering is needed.
 
-All release changes belong in the PR. Core preparation commits additions and deletions from release hooks but never pushes, tags or publishes. Validation independently generates the expected tree from the current base. A changed base SHA alone is fine; changed generated notes are not. Ordinary PRs with no version change pass release validation and still build unsigned.
+All release changes belong in one commit, including the version bump and generated files. Core preparation commits additions and deletions from release hooks but never pushes, tags or publishes. Validation independently generates the expected tree from the current base and requires exactly one commit ahead of that base. A changed base SHA alone is fine; changed generated notes are not. Ordinary PRs with no version change have no commit limit and still build unsigned.
+
+To run the same content and commit-count validation locally from a release branch:
+
+``` bash
+git fetch origin main
+bundle exec bake gem:github:release:validate base=origin/main
+```
+
+Replace `main` with your configured default branch. When correcting a release, amend the existing commit or regenerate it with `refresh=true` instead of adding fixup commits. Amended content must still match the generated release; changes to release notes or generation hooks usually belong on the default branch followed by a refresh.
 
 ## Publish the merged release
 
-Merging into the configured default branch triggers `release-publish.yaml` through its `push` event. Inspection uses the exact pushed SHA and resolves its associated PR through GitHub. Publication requires one matching merged PR in this repository, targeting the configured branch, with that exact merge commit. Ordinary changes do not publish; release changes without a matching merged PR fail inspection. Both merge commits and squash merges are supported, including merged fork PRs.
+Merging into the configured default branch triggers `release-publish.yaml` through its `push` event. Inspection uses the exact pushed SHA and resolves its associated PR through GitHub. Publication requires one matching merged PR in this repository, targeting the configured branch, with that exact resulting commit. Ordinary changes do not publish; release changes without a matching merged PR fail inspection. Single-commit release PRs support squash merging, rebase merging, and merge commits, including merged fork PRs. Publishing validates against the resulting commit's first parent, which is the default branch immediately before the release landed.
 
 Each release must land as the tip of its own push, as it does when merging a PR through GitHub. Later pushes do not change a pending release's source: inspection and publishing remain pinned to the original commit, and reruns use the same event. Do not combine a release and later changes into one direct push. If you automate merging, use a GitHub App or personal access token; pushes made using a workflow's `GITHUB_TOKEN` do not trigger another workflow.
 
@@ -45,4 +54,4 @@ bundle exec bake gem:github:release:patch refresh=true
 gh workflow run release-prepare.yaml -f bump=patch -f refresh=true
 ```
 
-Refresh first pushes the complete previous release commit to `release-backups/vVERSION/OLD_SHA`, including manual edits. It then regenerates in a clean worktree from the current default branch, validates, and updates the existing release branch using an explicit `--force-with-lease`. A concurrent remote edit causes the push to fail. Existing local release branches are left intact. Review the backup against the refreshed PR; incorporate necessary manual changes into the default branch or generation hooks and refresh again. Keep the backup until that review is complete. Replace `main` and `patch` with your configured branch and original bump type.
+Refresh first pushes the complete previous release commit to `release-backups/vVERSION/OLD_SHA`, including manual edits. It then regenerates one release commit in a clean worktree from the current default branch, validates, and updates the existing release branch using an explicit `--force-with-lease`. A concurrent remote edit causes the push to fail. Existing local release branches are left intact. Review the backup against the refreshed PR; incorporate necessary manual changes into the default branch or generation hooks and refresh again. Keep the backup until that review is complete. Replace `main` and `patch` with your configured branch and original bump type.

data/context/verifying-releases.md

@@ -6,7 +6,7 @@ Use this when checking a completed release or confirming which source commit pro
 
 ## What publishing verifies
 
-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:
+After squash, rebase, or merge, the publishing workflow verifies GitHub's merged PR record and ancestry, then checks out the exact resulting commit. Each release PR contains one commit, so the resulting commit's **first parent** is the default branch immediately before the release landed. Later development on the default branch is allowed. Publishing regenerates against that first parent, builds in a clean worktree, optionally certificate-signs, and creates two attestations over the final bytes:
 
 - A Sigstore bundle submitted explicitly with `gem push --attestation` using RubyGems 4.0.21.
 - 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.

data/lib/bake/gem/github/project.rb

@@ -78,7 +78,7 @@ module Bake
 						candidate = @release.resolve("HEAD")
 					end
 					
-					metadata = @release.validate(base: base, candidate: candidate)
+					metadata = validate(base: base, candidate: candidate, optional: false)
 					raise "Release branch does not contain the requested version #{version}." unless metadata.fetch(:version) == version
 					
 					push("--force-with-lease=#{release_ref}:#{remote_commit}", "#{candidate}:#{release_ref}")
@@ -90,6 +90,23 @@ module Bake
 					)
 				end
 				
+				# Validate PR content and require each proposed release to contain exactly one commit.
+				# @parameter base [String] The current target commit.
+				# @parameter candidate [String] The proposed PR head.
+				# @parameter optional [Boolean] Accept ordinary PRs without a version change.
+				# @returns [Hash | Nil] Release metadata, or nil for an ordinary PR.
+				# @raises [RuntimeError] If the release content is invalid or the release contains multiple commits.
+				def validate(base:, candidate: "HEAD", optional: true)
+					metadata = @release.validate(base: base, candidate: candidate, optional: optional)
+					if metadata
+						range = "#{metadata.fetch(:base)}..#{metadata.fetch(:commit)}"
+						count = readlines("git", "rev-list", "--count", range, chdir: @root).join.strip
+						raise "Release PRs must contain exactly one commit. Amend or regenerate the release commit instead of adding commits." unless count == "1"
+					end
+					
+					return metadata
+				end
+				
 				# Resolve a merged PR through GitHub, and require its actual merge commit in default-branch history.
 				# @parameter number [String | Integer] The positive PR number.
 				# @returns [Hash] GitHub PR data with string keys, including `number` and `merge_commit_sha`.
@@ -157,6 +174,7 @@ module Bake
 				
 				# Return a read-only comparison of managed settings and current repository settings.
 				# @returns [Hash] Desired rules, existing rules, environments, optional environment changes, and expected Trusted Publisher settings. This does not verify RubyGems ownership or publisher configuration.
+				# @raises [RuntimeError] If a reviewer team is secret or belongs to another organization.
 				def doctor
 					{
 						desired_rules: Setup.rules(@config),
@@ -174,8 +192,9 @@ module Bake
 				
 				# Apply the named rulesets and configured reviewers for an existing environment. Invoke after reviewing doctor output.
 				# Preserves the environment's wait timer, self-review prevention, administrator bypass, and branch restrictions.
+				# Reads back updated environment settings to verify GitHub retained them.
 				# @returns [Hash] The desired ruleset payloads after successful application.
-				# @raises [RuntimeError] If more than one existing ruleset has a managed name.
+				# @raises [RuntimeError] If a reviewer team is unsuitable, managed rulesets are ambiguous, or environment verification fails. Earlier updates may already have completed.
 				# @raises [Bake::Gem::CommandExecutionError] If an API operation fails; earlier updates may already have completed.
 				def apply
 					changes = environment_changes
@@ -193,6 +212,9 @@ module Bake
 					
 					if changes && changes.fetch(:current) != changes.fetch(:desired)
 						write_api("repos/#{@repository}/#{environment_path}", changes.fetch(:desired), method: "PUT")
+						unless environment_settings == changes.fetch(:desired)
+							raise "GitHub did not retain the requested settings for environment #{changes.fetch(:name)}. Check its reviewers and protection rules in GitHub, then rerun gem:github:setup:plan."
+						end
 					end
 					
 					return rules
@@ -209,19 +231,26 @@ module Bake
 					return nil unless @config.key?("reviewers")
 					Setup.validate_reviewers(@config["reviewers"])
 					
+					current = environment_settings
+					reviewers = @config.fetch("reviewers").map{|name| resolve_reviewer(name)}.uniq.sort_by{|reviewer| reviewer.values_at(:type, :id)}
+					
+					return {name: @config.fetch("environment"), current: current, desired: current.merge(reviewers: reviewers)}
+				end
+				
+				# Read the environment settings, comparing reviewer identities independently of their order.
+				def environment_settings
 					environment = api(environment_path)
 					protections = environment.fetch("protection_rules").to_h{|rule| [rule.fetch("type"), rule]}
 					reviews = protections.fetch("required_reviewers", {})
-					current = {
+					reviewers = reviews.fetch("reviewers", []).map{|entry| {type: entry.fetch("type"), id: entry.fetch("reviewer").fetch("id")}}
+					
+					return {
 						wait_timer: protections.fetch("wait_timer", {}).fetch("wait_timer", 0),
 						prevent_self_review: reviews.fetch("prevent_self_review", false),
 						can_admins_bypass: environment.fetch("can_admins_bypass"),
 						deployment_branch_policy: environment.fetch("deployment_branch_policy"),
-						reviewers: reviews.fetch("reviewers", []).map{|entry| {type: entry.fetch("type"), id: entry.fetch("reviewer").fetch("id")}},
+						reviewers: reviewers.uniq.sort_by{|reviewer| reviewer.values_at(:type, :id)},
 					}
-					reviewers = @config.fetch("reviewers").map{|name| resolve_reviewer(name)}
-					
-					return {name: @config.fetch("environment"), current: current, desired: current.merge(reviewers: reviewers)}
 				end
 				
 				def resolve_reviewer(name)
@@ -235,6 +264,9 @@ module Bake
 						type = "User"
 					end
 					response = JSON.parse(readlines("gh", "api", path, chdir: @root).join)
+					if type == "Team" && response.fetch("privacy") == "secret"
+						raise "Reviewer team #{name} is Secret. Change its visibility to Visible in GitHub team settings before running setup."
+					end
 					
 					return {type: type, id: response.fetch("id")}
 				end

data/lib/bake/gem/github/setup.rb

@@ -89,7 +89,7 @@ module Bake
 									require_last_push_approval: true,
 									required_review_thread_resolution: true,
 									require_code_owner_review: false,
-									allowed_merge_methods: ["merge", "squash"],
+									allowed_merge_methods: ["merge", "squash", "rebase"],
 								},
 							}],
 						),

data/lib/bake/gem/github/version.rb

@@ -9,7 +9,7 @@ module Bake
 	module Gem
 		# GitHub pull request and release orchestration for bake-gem.
 		module GitHub
-			VERSION = "0.3.1"
+			VERSION = "0.5.0"
 		end
 	end
 end

data/readme.md

@@ -24,6 +24,14 @@ Please see the [project documentation](https://socketry.github.io/bake-gem-githu
 
 Please see the [project releases](https://socketry.github.io/bake-gem-github/releases/index) for all releases.
 
+### v0.5.0
+
+  - Support rebase merging by requiring each release PR to contain exactly one commit, while leaving ordinary PRs unrestricted. Generated rules allow merge, squash, and rebase methods according to repository settings.
+
+### v0.4.0
+
+  - Reject Secret environment reviewer teams before applying release settings, and verify that GitHub retained the requested reviewers and existing protections after updating the environment.
+
 ### v0.3.1
 
   - Publish validated release PRs from pushes to the default branch, retaining the exact merged commit and environment approval without requiring `pull_request_target`.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.5.0
+
+  - Support rebase merging by requiring each release PR to contain exactly one commit, while leaving ordinary PRs unrestricted. Generated rules allow merge, squash, and rebase methods according to repository settings.
+
+## v0.4.0
+
+  - Reject Secret environment reviewer teams before applying release settings, and verify that GitHub retained the requested reviewers and existing protections after updating the environment.
+
 ## v0.3.1
 
   - Publish validated release PRs from pushes to the default branch, retaining the exact merged commit and environment approval without requiring `pull_request_target`.

data/templates/release-validate.yaml.erb

@@ -27,6 +27,6 @@ jobs:
       - name: Regenerate release content
         env:
           RELEASE_BASE: ${{ github.event.pull_request.base.sha }}
-        run: bundle exec bake gem:release:validate "base=$RELEASE_BASE" optional=true
+        run: bundle exec bake gem:github:release:validate "base=$RELEASE_BASE"
       - name: Build unsigned package
         run: bundle exec bake gem:build signing_key=false

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bake-gem-github
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Samuel Williams

metadata.gz.sig

@@ -1,2 +1 @@
-
��iH��
��^�*�CK���$��_9#��G�~/�5�t�$
-㋏R5�  ����k��������3�C<j�g>b�i�"������Pkh�m}T2�;r���PV}|(gC�o�l���F�X䔅�SI�WY;���0�UԦ�h!*#�Z�@���5���*�=��&��Ϸ�S�@���Ȧ�vZ"��}�r�[��VG�[��1��V���h����
�\eB����6%w;*��7S����x�#D���6���ﻳ:@y|��ky��@�dV��&�G.z
.H��
+���y0�a�tq��ok��̤�ebَk��z�3�
!�:ւ/�đ�U����кq�-�e���V��<ӽ�0["�	n���xϼ�ڄd�eS_��;��J��1#����4 D��w�0��P�t܁G)!�����ș?Ǔ[䱭&�^O@���wƁ}E�x��x����F�#U3w�.D2��ϒ\�,m����O��pV�u�!&�M]�Z��4�}jv���s2����W�=I���~�|�RhE��5��LK����l^v���3ӏ�:�,&z-��M
Ns�7���4�	�X�թ��Fbrjst6P�����b�"���֝�S�D��h��I�@����+P�ߗ�