Repository navigation
Decide: document vs preflight-check the Actions PR-creation repo setting #1762
Description
The situation
Consumer repos must enable Settings → Actions → General → Workflow permissions → Allow GitHub Actions to create and approve pull requests, or Squad's PR creation fails.
Empirically confirmed universal during the 2026-08-19 live run: freshly created repos default can_approve_pull_request_reviews to false, so every new adopter hits this.
Documentation status — already done
docs/src/content/docs/guide/gh-aw.md already carries a setup section covering this. Verified present on dev.
The actual decision
Is documentation sufficient, or should Squad's connect/adopt path add a preflight check that probes the setting and tells the user exactly what to flip?
Arguments for a preflight check
- It's a 100% hit rate — literally every new adopter
- The failure mode is opaque: PR creation fails with a permissions error that doesn't name the setting
- The setting is readable via the API, so the check is cheap
Arguments against
- More surface area in the adopt path
- Requires a token scope that can read repo Actions settings
Sequencing note
This shares the adoption-preflight surface with #1748 (dependency additions). If a preflight mechanism gets built, both checks should ride the same one rather than each growing a bespoke probe.
Either sequence these together, or explicitly decide they're independent — but decide deliberately rather than by accident.
Origin
Finding E from the 2026-08-19 live end-to-end run against a real .NET repo.
Activity
bradygaster commentedon Aug 20, 2026
Flight sequencing note — revised 2026-08-20.
Wave: 1.
Depends on: nothing in this stream.
Blocks:
Safe to run in parallel with: #1772, #1770, #1760, #1761, #1768, #1756, and #1759. Do not start #1748 until this decision is made.
Why / evidence: the Actions PR-creation setting is already documented in
docs/src/content/docs/guide/gh-aw.mdlines 63-82, but the workflow adoption paths have no preflight step today:workflows/squad.mdsquad-connectis lines 420-434 andsquad-adoptis lines 436-451. #1748 asks for a repo-level dependency-change policy; its structural guard is inworkflows/squad-implement-worker.mdprotected-files lines 170-181 and excluded-files lines 182-196. Same product surface, no line overlap yet.bradygaster commentedon Aug 20, 2026
Closing — docs already cover this; remaining action is a repo settings flip, not code.
PAO confirmed the documentation at \docs/src/content/docs/guide/gh-aw.md:63-82\ already covers the 'Allow GitHub Actions to create and approve pull requests' setting. Flight's verdict: the remaining gap is not a code or doc task — it's enabling that setting on the E2E fixture repo (\�radygaster/aspiregregator-squad-e2e) as a preflight step before the 2026-08-21 run.
The preflight probe (detecting the setting programmatically) was considered and deferred to \squad health\ (#1605), which is a wave:3+ item. Adding a runtime check here would be over-engineering a one-time preflight action.
Action for E2E readiness: Enable 'Allow GitHub Actions to create and approve pull requests' on \�radygaster/aspiregregator-squad-e2e\ before tomorrow's run. This is a five-second Settings click, not a work item.