@@ -119,6 +119,9 @@ GitHub Actions bot comment, so editable PR prose cannot rebind an old bootstrap
119119run to a changed branch head. Only after that base-controlled canary succeeds
120120should the Cast/bootstrap lifecycle be treated as trusted. Do not enable the
121121required check in a ruleset before this post-install canary has been observed.
122+ The review uses only the native GitHub Actions/gh-aw runtime identity; it does
123+ not require a reviewer PAT, GitHub App, private key, secret, environment, or
124+ external service.
122125
123126Step 2 deliberately checks Issues before creating the bootstrap branch or
124127installing any workflow. Squad commands are issue comments, and the merged
@@ -298,21 +301,17 @@ source/lock pairs, and one coherent 40-character revision.
298301
299302On a clean repository, ` gh aw add ` reports these expected safe-update changes:
300303
301- - Restricted secrets: ` SQUAD_GITHUB_APP_PRIVATE_KEY ` , ` SQUAD_GITHUB_TOKEN ` , and
302- ` SQUAD_REVIEW_APP_PRIVATE_KEY `
304+ - Restricted secrets: ` SQUAD_GITHUB_APP_PRIVATE_KEY ` and ` SQUAD_GITHUB_TOKEN `
303305- Action: ` bradygaster/squad/.github/actions/squad-init `
304306
305307> ** These are referenced names, not prerequisites.** ` gh aw add ` lists the secrets
306308> the workflows * reference* so you can approve that surface — it is not asking you
307- > to supply them during compilation. ` SQUAD_GITHUB_APP_PRIVATE_KEY ` and
308- > ` SQUAD_GITHUB_TOKEN ` remain optional activation credentials; single -repo
309- > activation can use the built-in ` github.token ` . Configure those only for cross-repo access or
309+ > to supply them. Both secrets are optional, they need not exist, and you do not
310+ > need to create either one to enlist a repository. Single -repo activation runs on
311+ > the built-in ` github.token ` . Configure these only for cross-repo access or
310312> elevated permissions — see [ enhanced permissions with a GitHub
311313> App] ( #optional-enhanced-permissions-with-a-github-app ) and [ PAT
312- > fallback] ( #optional-pat-fallback ) . ` SQUAD_REVIEW_APP_PRIVATE_KEY ` is different:
313- > it belongs only in the branch-restricted ` squad-review-authority ` environment
314- > described below. Trusted required-check publication intentionally fails closed
315- > until that external prerequisite is provisioned.
314+ > fallback] ( #optional-pat-fallback ) .
316315
317316Review the report before approving it. If it contains only those documented
318317entries, complete the first-install approval with:
@@ -436,47 +435,6 @@ a Personal Access Token:
436435
437436**Auth precedence:** GitHub App token → `SQUAD_GITHUB_TOKEN` → `github.token`.
438437
439- ### Required: dedicated review authority App
440-
441- The required `Squad Review / review` check must not use `github.token`.
442- `github.token` checks are owned by the shared GitHub Actions App
443- (`id: 15368`, slug: `github-actions`), which is also available to ordinary
444- same-repository PR workflows. The reviewer instead mints a short-lived token
445- for a dedicated GitHub App inside a protected environment and has no fallback.
446-
447- Before expecting the post-install Cast canary to pass:
448-
449- 1. Create a dedicated GitHub App with repository **Checks: read and write** and
450- read access to Actions, contents, metadata, and pull requests. Install it
451- only on the consumer repository.
452- 2. Create the Actions environment **`squad-review-authority`**.
453- 3. Configure a custom deployment branch policy containing exactly the
454- repository default branch. Do not allow wildcard, feature, release, tag, or
455- additional branch policies; a PR workflow must not be able to request this
456- environment from its own ref.
457- 4. Store these reviewer-specific values in that environment, not as
458- repository-level Actions secrets or variables:
459-
460- | Setting | Type | Purpose |
461- |---------|------|---------|
462- | `SQUAD_REVIEW_APP_ID` | Variable | Dedicated App numeric ID; must not be `15368` |
463- | `SQUAD_REVIEW_APP_SLUG` | Variable | Dedicated App slug; must not be `github-actions` |
464- | `SQUAD_REVIEW_APP_OWNER` | Variable | Repository owner where the App is installed |
465- | `SQUAD_REVIEW_APP_PRIVATE_KEY` | Secret | Dedicated App private key |
466-
467- The publisher validates the configured ID and slug, mints an installation token
468- inside the environment, publishes with that token, and validates the App
469- identity returned by the Checks API. Missing environment protection, missing
470- credentials, token-mint failure, Actions App identity, or any ID/slug mismatch
471- fails closed. An ordinary `github.token` may create a same-named check owned by
472- the Actions App, but it cannot update the dedicated App' s check and cannot
473- satisfy an integration-bound ruleset.
474-
475- Before rollout, verify the four reviewer-specific names are absent from
476- repository-level Actions secrets and variables. GitHub expression contexts can
477- otherwise fall back to a repository-scoped value with the same name. The hosted
478- controller treats that overlap as a hard configuration error.
479-
480438---
481439
482440## Supported-path validation checklist
@@ -1556,13 +1514,22 @@ exactly one pull request review. It returns:
15561514
15571515The trusted writer publishes these logical verdicts in a native ` COMMENT`
15581516review: GitHub does not permit an account to approve or request changes on its
1559- own PR. The native `Squad Review Authority / attest` job proves that the base-controlled
1560- workflow executed. Its publisher creates `Squad Review / review` on the exact
1561- PR head with a `squad-review-check/v1` attestation linked to that run. A
1562- PR-controlled workflow may create advisory output with the same display name,
1563- but it cannot satisfy the relay without the successful native authority job and
1564- exact event/base/head/run/App binding. The status check enforces
1565- `REQUEST_CHANGES`; no additional bot accounts or Apps are needed.
1517+ own PR. The final native job is named ` review` , so GitHub exposes the stable
1518+ required status context ` Squad Review / review` . It uses ` if: always ()` and
1519+ fails unless the agent, safe-output processing, and deterministic current-head
1520+ verdict gate all succeed. The relay independently binds the verdict to the exact
1521+ automatic ` pull_request_target` run, workflow path, immutable base/workflow SHA,
1522+ PR base/head, run ID and attempt, and that run attempt' s successful `review`
1523+ job. No custom Checks API publisher, reviewer credential, environment, hosted
1524+ attestor, or external service is involved.
1525+
1526+ Each successful run attempt starts with no verdict evidence for its exact run ID
1527+ and attempt, then publishes exactly one fresh safe-output review. Pre-existing
1528+ exact-attempt evidence is rejected rather than accepted through a `noop` or
1529+ deduplication path, because another PR-controlled workflow shares the
1530+ `github-actions[bot]` identity and could otherwise pre-seed a valid-looking
1531+ record. A rerun receives an incremented attempt and must publish a new review;
1532+ evidence from prior attempts is neither replayed nor reused.
15661533
15671534The reviewer has no file-editing, issue-creation,
15681535pull-request-creation, remediation, merge, or `APPROVE` authority. Its verdict
@@ -1576,9 +1543,9 @@ The lifecycle is:
15761543` ` `
15771544
15781545The epic relay repeats the guard before running the agent and before processing
1579- any outputs. It requires a clearing verdict, the successful native authority
1580- job from the base-controlled run, and the exact-head published check completed
1581- ** before merge ** for the merged PR' s **head SHA**, not the merge commit.
1546+ any outputs. It requires a clearing verdict and the successful native ` review `
1547+ job from the exact base-controlled run attempt completed ** before merge ** for
1548+ the merged PR' s **head SHA**, not the merge commit.
15821549Bypassing a missing Squad review at merge
15831550cannot silently advance the epic. Missing evidence stops the run with an explicit
15841551error; it never dispatches the next wave.
@@ -1588,29 +1555,38 @@ error; it never dispatches the next wave.
15881555The stable literal check name is **`Squad Review / review`**.
15891556There is no manual reviewer run. `/squad review` only explains how to rerun the
15901557existing automatic `pull_request_target` run, and only that exact base-controlled
1591- run ID, attempt, native authority job, and exact-head attestation can satisfy
1592- its emitted verdict and check .
1558+ run ID, attempt, native authority job, and exact-head verdict can satisfy the
1559+ relay .
15931560
15941561Brady (or the consumer repository administrator) must install/merge the complete
15951562generated bundle through the explicit human installation boundary, then observe
15961563a successful base-controlled `pull_request_target` check on the post-install
15971564draft Cast PR before
15981565changing rulesets. The installation PR itself is not evidence: its workflow and
1599- check name are controlled by that PR. The Cast canary remains intentionally red
1600- until the [dedicated review authority App](#required-dedicated-review-authority-app)
1601- and exact-default-branch environment policy are provisioned. Record the
1602- activation canary' s actual
1603- check name, external ID, details URL, attestation summary, and GitHub App ID
1604- and slug from the check-runs API. The attestation' s `publisher_app_id` and
1605- `publisher_app_slug` must equal the check' s returned App identity and must not
1606- be ` 15368` /` github-actions` . Enable the required context with that observed App ID
1607- on ` dev` ** only after advisory soak** has met the
1566+ check name are controlled by that PR. Record the activation canary' s exact
1567+ automatic run ID/attempt, workflow path and base SHA, native ` review` job
1568+ conclusion, exact PR head SHA, and the job' s native `Squad Review / review`
1569+ check-run binding. Enable the required context on `dev` **only after advisory soak** has met the
16081570evidence gate in #1734; promote to `main` after the agreed soak. This change
16091571does not modify repository rulesets and does not claim live soak evidence. Keep
16101572native human approving-review requirements enabled independently, with stale
1611- approvals dismissed. The bot' s `COMMENT` is not a human approval. Do not use an
1612- unobserved guessed App ID, a user-supplied integration ID, an Actions-owned
1613- same-name check, or the manual job.
1573+ approvals dismissed. The bot' s ` COMMENT` is not a human approval.
1574+ Require branches to be up to date before merge (or an equivalent merge-queue
1575+ freshness guarantee) so the required review run is always based on the current
1576+ default-branch workflow and guard. Merge the workflow installation first,
1577+ observe the post-merge Cast canary, and only then enable the required context.
1578+
1579+ GitHub' s context-only required-status-check configuration identifies the
1580+ context by name and does not, by itself, demonstrate that another workflow
1581+ cannot emit the same name. The relay is not vulnerable to that ambiguity
1582+ because it reads the exact trusted run attempt' s jobs. For authoritative merge enforcement, use a source-bound required-workflow or
1583+ equivalent ruleset when the repository' s GitHub plan and policy expose one. A
1584+ context-only `Squad Review / review` requirement is advisory because a
1585+ PR-controlled workflow may be able to emit the same workflow/job name through
1586+ the shared GitHub Actions identity. If source-bound enforcement is unavailable,
1587+ keep the same-name source-identity question explicit and retain independent
1588+ human review rather than relying on that context alone; do not invent a
1589+ credential or external attestor as a workaround.
16141590Because rulesets apply to all PRs, existing human/Copilot PRs must add committed
16151591attribution before enabling the requirement. Fork review remains unsupported;
16161592the workflow rejects foreign head repositories even though its base-controlled
0 commit comments