ci: run release-please under a PAT so release PRs get CI

.github/workflows/release-please.yml

@@ -5,10 +5,20 @@ on:
     branches:
       - main
 
-# The default GITHUB_TOKEN is enough for both steps the action performs, as
-# long as the repo has "Allow GitHub Actions to create and approve pull
-# requests" enabled (Settings -> Actions -> General) — without it, opening the
-# release PR fails.
+# Runs under a PAT (RELEASE_PLEASE_TOKEN), not the default GITHUB_TOKEN. Workflows
+# are not triggered by events a GITHUB_TOKEN causes, so a release PR opened with it
+# gets no CI run at all: `ci-green`, the check branch protection requires, never
+# reports, and the PR sits blocked with nothing failing to explain it. Opening the
+# PR as a user instead makes CI run on it like on any other PR. The token needs
+# Contents and Pull requests, both read/write, on this repo only — and it expires,
+# at which point releases stop being proposed until it is rotated.
+#
+# This also makes "Allow GitHub Actions to create and approve pull requests"
+# (Settings -> Actions -> General) irrelevant here: the PR no longer comes from
+# Actions. The permissions block below only covers the GITHUB_TOKEN, which the
+# action stops using once `token:` is set; it is kept for whoever goes back to it,
+# which means deleting the `token:` line — deleting only the secret leaves the
+# input present and empty, and a default only applies to an omitted input.
 permissions:
   contents: write
   pull-requests: write
@@ -19,5 +29,6 @@ jobs:
     steps:
       - uses: googleapis/release-please-action@v4
         with:
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
           config-file: release-please-config.json
           manifest-file: .release-please-manifest.json

docs/OVERVIEW.md

@@ -575,9 +575,14 @@ code-server to respond, and opens the window correctly.
   `0.0.0` and the history is all `feat`/`fix`, which never produces a major on its own. The
   template had been in real use across projects well before this point, so naming the first tag
   `1.0.0` describes its actual state rather than what the commit history could infer.
-- **Depends on a repo setting**: "Allow GitHub Actions to create and approve pull requests"
-  (Settings → Actions → General). The workflow uses the default `GITHUB_TOKEN` rather than a PAT,
-  and without that setting the action fails at the point of opening the release PR.
+- **Runs under a PAT, not the default `GITHUB_TOKEN`** — the `RELEASE_PLEASE_TOKEN` secret, needing
+  Contents and Pull requests (read/write) on this repo only. The reason is the next point. Two
+  consequences worth keeping in mind: the repo setting "Allow GitHub Actions to create and approve
+  pull requests" no longer matters here, because the PR does not come from Actions; and the token
+  expires, at which point releases silently stop being proposed until it is rotated. Going back to
+  the `GITHUB_TOKEN` means deleting the `token:` line, not just the secret: the action's default is
+  `${{ github.token }}`, but a default only applies to an *omitted* input, and a deleted secret
+  leaves `token:` present and empty.
 - **`main` is protected**, which is also why the repo is public — branch protection is a paid
   feature on private repos. Every change lands through a pull request; no approvals are required
   (single maintainer) but the rule applies to administrators too, and force-pushes and branch
@@ -586,12 +591,12 @@ code-server to respond, and opens the window correctly.
   that stops reporting blocks every merge forever. "Require branches to be up to date before
   merging" is deliberately **off** — see the next point for why turning it on would deadlock every
   release.
-- **A release PR needs one manual step, and it is not obvious.** Workflows are not triggered by
-  events that the `GITHUB_TOKEN` causes, so the PR release-please opens gets no CI run at all —
-  `ci-green` never reports, and a required check that never reports leaves the PR `BLOCKED` with
-  zero failures to look at. Closing and reopening the PR from a normal account produces the run,
-  because the `reopened` event then comes from a user. Giving release-please a PAT instead would
-  remove the step permanently, at the cost of a secret to rotate. Two related traps sit next to
+- **Why the PAT: a `GITHUB_TOKEN` release PR can never satisfy a required check.** Workflows are not
+  triggered by events that the `GITHUB_TOKEN` causes, so the PR release-please opened got no CI run
+  at all — `ci-green` never reported, and a required check that never reports leaves the PR
+  `BLOCKED` with zero failures to look at. Closing and reopening the PR from a normal account is
+  the manual way out, since the `reopened` event then comes from a user; that is what 1.0.2 needed,
+  twice, before the PAT replaced it. Two related traps sit next to
   this one: a `pull_request` run uses the workflow file **from the head branch**, not from the
   merge commit, so a check added to `main` after the release branch was cut will never appear on
   that PR (the branch has to be recreated: close the PR, delete the branch, re-run the workflow);