ci(release): settle directly, gated by the release environment

.github/workflows/on-release.yml

@@ -2,17 +2,18 @@ name: On Release
 
 # Publish target for a stateless-validator release: the two binaries as
 # downloads on the GitHub Release page, with a SHA256SUMS file. Runs when the
-# release pipeline publishes the Release (release-publish creates it after
-# the tag), and on demand for a rehearsal on a tag ref:
+# release pipeline publishes the Release (release-settle creates it right
+# after the tag), and on demand for a rehearsal on a tag ref:
 #   gh workflow run on-release.yml --ref vX.Y.Z -f dry_run=true
 # The tag being released is always the run's own ref; there is no tag input.
 #
 # This file must exist on the release branch: a `release` event resolves the
 # workflow from the tagged commit's tree, not from the default branch, and the
 # tag sits on the release branch. A branch cut from a default branch that has
 # this file carries it; a branch cut before it landed needs it cherry-picked
-# (via its own PR — the `release-*` ruleset requires one) before the settle PR
-# merges, or the Release publishes with nothing attached and no failed run.
+# (via its own PR — the `release-*` ruleset requires one) before release-settle
+# is dispatched, or the Release publishes with nothing attached and no failed
+# run; release-settle warns when the tip lacks a workflow main has.
 # A rehearsal likewise only works on a tag whose tree has this file.
 #
 # The internal archive to Artifact Registry stays in release.yaml and

.github/workflows/release-publish.yml

@@ -8,6 +8,11 @@ name: Release Publish
 #
 # This file must exist on the release branch (it does, when the branch is cut
 # from a default branch that has it).
+#
+# Only settlement by PR reaches this workflow. release-settle.yml settles
+# directly (`settle_mode: direct`, gated by the `release` environment) and
+# publishes from its own job, so nothing here fires unless this repo goes
+# back to PR mode; the job gate rejects any settle PR the app did not open.
 
 on:
   pull_request:

.github/workflows/release-settle.yml

@@ -1,10 +1,19 @@
 name: Release Settle
 
-# Propose settling a release candidate. Dispatch from any branch with the
+# Settle a release candidate. Dispatch from the default branch with the
 # version and the full SHA of the release-branch tip; the shared action
 # verifies it, generates release notes from the commits since the previous
-# tag, writes them to the changelog, and opens a settle PR onto the release
-# branch. Merging that PR is the settlement decision (release-publish tags it).
+# tag, commits them to the changelog on the release branch, and publishes:
+# annotated tag at that commit, GitHub Release with the notes (on-release.yml
+# then attaches the binaries; release.yaml / release-tracing.yaml archive to
+# Artifact Registry on the tag push).
+#
+# The dispatch is the settlement decision, gated twice: the `release`
+# environment on the job (its required reviewers approve the run before it
+# starts; its deployment branch policy allows only the default branch) and
+# `settlers` in the action (the dispatching actor must be a repository
+# admin). The app is a bypass actor on the release-branch and `v*` tag
+# rulesets, which is what lets the settle commit and the tag land.
 
 on:
   workflow_dispatch:
@@ -18,8 +27,8 @@ on:
         required: true
         type: string
 
-# One settle per version: two dispatches for the same version would both
-# force-push the same settle branch. Queue, never cancel.
+# One settle per version: two dispatches for the same version would race on
+# the release branch. Queue, never cancel.
 concurrency:
   group: ${{ github.workflow }}-${{ inputs.version }}
   cancel-in-progress: false
@@ -30,6 +39,7 @@ permissions:
 jobs:
   settle:
     runs-on: ubuntu-latest
+    environment: release
     steps:
       - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3
         id: app-token
@@ -50,3 +60,5 @@ jobs:
           version_file: Cargo.toml
           version_pattern: toml
           changelog_file: CHANGELOG.md
+          settle_mode: direct
+          settlers: admin

CHANGELOG.md

@@ -1,8 +1,8 @@
 # Changelog
 
 All notable changes to stateless-validator are recorded here, newest first.
-Entries are generated by the release flow from merged PR titles; edit an
-entry in its release candidate or settle PR if the wording needs work.
+Entries are generated by the release flow from merged PR titles.
+Fix wording in the release candidate PR while it is open, or, after it merges, by a PR onto the release branch before settlement is dispatched.
 
 ## v2.0.18