Cut releases from the GitHub Releases UI

[kfalconer]

Why

Publishing v0.1.0 from the Releases UI half-failed. The gem pushed to RubyGems fine, then the run went red on the last step:

✓ Verify the tag matches the gem version
✓ Push to RubyGems.org
X Create the GitHub release   ← HTTP 422 Release.tag_name already exists

The workflow triggered on push: tags and created the GitHub release itself, so when the release came from the UI it was trying to create one that already existed. Nothing is broken on RubyGems — 0.1.0 is live — but the workflow did the opposite of the intended flow.

What changed

• Trigger on release: published instead of push: tags, and drop the release-creation step. The release already exists by the time the workflow fires.
• Read the tag from github.event.release.tag_name rather than GITHUB_REF_NAME, and check out that tag explicitly.
• contents: write → contents: read on the publishing job. GitHub creates the tag before the workflow runs, so bundler's release:source_control_push — tag_version { git_push } unless already_tagged? — always takes the already-tagged branch and never pushes. Worth tightening because this job holds the OIDC publishing credentials.
• CHANGELOG.md now links to each release, since Generate release notes is the preferred source of notes. The ## [x.y.z] headings were already reference links with no definitions, so they were rendering as literal brackets; this adds the definitions. Also corrects the 0.1.0 date to the day it actually published.
• README release instructions rewritten for the UI flow — the old CLI git tag && git push steps were wrong.

The version-vs-tag guard stays. Note it now behaves differently on a missing v prefix: the old tags: ["v*"] glob meant a bare 0.2.0 tag triggered nothing at all, whereas now it triggers and fails the guard before publishing. Same outcome, clearer failure.

Verification

The parts that can be checked without cutting a release:

• Trusted publishing and the release environment are confirmed working end-to-end by the v0.1.0 run — only the release-creation step failed.
• contents: read verified against the installed bundler's gem_helper.rb, not from memory, and corroborated by the v0.1.0 run's push step succeeding with a UI-created tag already present.
• All four changelog link targets return 200; every heading resolves, no orphan definitions.
• bundle exec rake spec → 19 examples, 0 failures. Nothing under lib/ was touched.

What can't be verified until it merges: release: published won't fire from a branch, and GitHub resolves release.yml from the commit the release points at — so the next release has to be cut after this is on master.

🤖 Generated with Claude Code