docs(integration): remove stale release_token path + clarify PAT-required for required-checks repos #333

New issue

Closed

opened 2026-07-03 13:35:59 +02:00 by bosun · 0 comments

bosun commented

2026-07-03 13:35:59 +02:00

Owner

Finding

Two stale/contradictory in docs/integration.md:

release_token stale: docs describe secrets.release_token. Reusable workflow declares no such secret; reads RELEASE_TOOLKIT_TOKEN + GITHUB_TOKEN. Path β is unimplemented documentation.
No-token path over-optimistic: docs say result is a manifest PR requiring one manual merge. scripts/release-prep.sh:572-580 says: "the rolling PR required checks never run and the PR cannot merge." Dedicated PAT is operationally NECESSARY for required-checks repos, not optional.

Blocking rationale

Adopters following docs hit dead-ends. v1.0.0 adopter-facing docs must be accurate.

Fix

Remove all release_token references (or implement)
Rewrite no-token section: required-checks repos need dedicated PAT, not just for autonomy
Cross-link to release-please system-token limitation docs

Anchor

External correctness cold-read (anonymous ChatGPT session, uploaded to operator 2026-07-03). Full review surfaced 10 findings across 5 blocking-v1.0.0 + 2 should-fix pre-v1.0.0 + 3 post-v1.0.0 backlog. This tracker addresses one of them.

BLOCKING v1.0.0.

## Finding Two stale/contradictory in `docs/integration.md`: 1. **release_token stale**: docs describe `secrets.release_token`. Reusable workflow declares no such secret; reads `RELEASE_TOOLKIT_TOKEN` + `GITHUB_TOKEN`. Path β is unimplemented documentation. 2. **No-token path over-optimistic**: docs say result is a manifest PR requiring one manual merge. `scripts/release-prep.sh:572-580` says: "the rolling PR required checks never run and the PR cannot merge." Dedicated PAT is operationally NECESSARY for required-checks repos, not optional. ## Blocking rationale Adopters following docs hit dead-ends. v1.0.0 adopter-facing docs must be accurate. ## Fix - Remove all `release_token` references (or implement) - Rewrite no-token section: required-checks repos need dedicated PAT, not just for autonomy - Cross-link to release-please system-token limitation docs ## Anchor External correctness cold-read (anonymous ChatGPT session, uploaded to operator 2026-07-03). Full review surfaced 10 findings across 5 blocking-v1.0.0 + 2 should-fix pre-v1.0.0 + 3 post-v1.0.0 backlog. This tracker addresses one of them. BLOCKING v1.0.0.

bosun added the

priority/critical

size/M

kind/docs

labels

2026-07-03 13:35:59 +02:00