Skip to content

Commit fa9dd45

Browse files
authored
Merge branch 'dev' into bradygaster-orchestration-scope-control
2 parents 562b7f1 + 6ec06cc commit fa9dd45

23 files changed

Lines changed: 678 additions & 1211 deletions

File tree

‎.changeset/dedicated-review-app.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,10 @@
33
"@bradygaster/squad-sdk": patch
44
---
55

6-
Require a dedicated, branch-restricted GitHub App identity for authoritative Squad review checks.
6+
Use the base-controlled deterministic relay's native `Squad Review / review`
7+
job as the authoritative review result only when it validates the exact trusted
8+
automatic workflow run. Authoritative merge enforcement requires a source-bound
9+
required-workflow or equivalent ruleset; where that is unavailable, the context
10+
is advisory and an independent human approving review remains required. This
11+
path needs no separately provisioned reviewer App, token, private key, secret,
12+
environment, or custom Checks API publisher.

‎.github/agents.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -35,12 +35,14 @@ GitHub Agentic Workflows (`gh-aw`) are composable AI workflows triggered by slas
3535
> the repository's default branch.
3636
> The installation PR is a manual trust boundary: its PR-controlled workflow
3737
> cannot mint a trusted Squad verdict. After merge, require the automatically
38-
> opened Cast PR to pass the exact-head `Squad Review / review` attestation from
39-
> the base-controlled `pull_request_target` authority before treating bootstrap
40-
> or lifecycle automation as trusted. That check must be published by a
41-
> dedicated GitHub App token minted only inside the exact-default-branch
42-
> `squad-review-authority` environment. Missing or misconfigured reviewer
43-
> credentials fail closed; the workflow never falls back to `github.token`.
38+
> opened Cast PR to pass the deterministic relay's native
39+
> `Squad Review / review` job, which is authoritative only when it validates the
40+
> exact trusted automatic run from the base-controlled `pull_request_target`
41+
> workflow. Authoritative merge enforcement requires a source-bound
42+
> required-workflow or equivalent ruleset. Where source binding is unavailable,
43+
> treat the context as advisory and continue to require an independent human
44+
> approving review. The relay requires no separate PAT, GitHub App, private key,
45+
> secret, environment, or external service.
4446
4547
The quick start installs this workflow set:
4648

‎.squad-templates/skills/gh-aw-enlistment/SKILL.md‎

Lines changed: 35 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -182,17 +182,17 @@ uses a moving branch reference.
182182
On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**:
183183

184184
<!-- allowlist-start -->
185-
- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`**,
186-
**`SQUAD_GITHUB_TOKEN`**, and **`SQUAD_REVIEW_APP_PRIVATE_KEY`**
185+
- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`**
187186
- Action: **`bradygaster/squad/.github/actions/squad-init`**
188187
<!-- allowlist-end -->
189188

190-
> **Compilation approval is not credential provisioning.** `gh aw add` lists
191-
> referenced names so you can approve the surface. `SQUAD_GITHUB_APP_PRIVATE_KEY`
192-
> and `SQUAD_GITHUB_TOKEN` remain optional activation credentials.
193-
> `SQUAD_REVIEW_APP_PRIVATE_KEY` is different: trusted check publication requires
194-
> it in the exact-default-branch `squad-review-authority` environment. Never put
195-
> reviewer credentials at repository scope and never fall back to `github.token`.
189+
> **These are referenced names, not prerequisites.** `gh aw add` lists the secrets
190+
> the workflows *reference* so you can approve that surface — it is not asking you
191+
> to supply them. Both secrets are optional, they need not exist, and neither is
192+
> required to enlist a repository. Single-repo activation runs on the built-in
193+
> `github.token`. Configure them only for cross-repo access or elevated
194+
> permissions. Auth precedence: GitHub App token, then the PAT, then
195+
> `github.token`. Never block an enlistment waiting for a credential.
196196
197197
If — and only if — the report contains exactly those documented entries, complete
198198
the one-time approval:
@@ -284,25 +284,30 @@ gh pr checks --watch
284284
`main`.
285285
- Request Copilot review, address feedback, and wait for required checks.
286286

287-
### 9. Verify the external review-authority prerequisite when API access permits
288-
289-
Before claiming trusted review is ready, query the repository environment. It
290-
must be named `squad-review-authority`, use custom deployment branch policies,
291-
allow exactly the captured `${default_branch}`, contain the environment secret
292-
`SQUAD_REVIEW_APP_PRIVATE_KEY`, and define environment variables
293-
`SQUAD_REVIEW_APP_ID`, `SQUAD_REVIEW_APP_SLUG`, and
294-
`SQUAD_REVIEW_APP_OWNER`. The App ID/slug must differ from
295-
`15368`/`github-actions`. All four reviewer-specific names must also be absent
296-
from repository-level Actions secrets and variables; repository fallback does
297-
not satisfy this gate.
298-
299-
If the authenticated account cannot read environment configuration, or any
300-
requirement is absent, report the exact external prerequisite and do not claim
301-
the required check is trusted. The installation PR remains a human boundary;
302-
after it merges, the Cast canary intentionally fails closed until an
303-
administrator provisions the environment and reruns the base-controlled
304-
review. Configure a ruleset only from the canary check's observed App
305-
integration ID, never from user input or a guessed value.
287+
### 9. Verify the native review contract after merge
288+
289+
The installation PR remains an explicit human trust boundary. After a human
290+
merges it, inspect the automatically opened Cast PR and require the native
291+
`Squad Review / review` job from the base-controlled `pull_request_target`
292+
workflow to succeed. Verify the exact workflow path, immutable base/workflow
293+
SHA, PR base/head, run ID and attempt, successful `review` job, and exact-head
294+
GitHub Actions check-run binding.
295+
296+
This review path uses only the native GitHub Actions/gh-aw runtime identity.
297+
Never request or provision a reviewer PAT, GitHub App, private key, secret,
298+
environment, hosted attestor, callback, or external service. The optional
299+
`SQUAD_GITHUB_APP_*` and `SQUAD_GITHUB_TOKEN` activation credentials remain
300+
unrelated to reviewer authority.
301+
302+
For authoritative merge enforcement, use a source-bound required-workflow or
303+
equivalent ruleset when available. A context-only requirement for
304+
`Squad Review / review` is advisory because a PR-controlled workflow may be
305+
able to emit the same workflow/job name through the shared GitHub Actions
306+
identity. If source-bound enforcement is unavailable, retain independent human
307+
review rather than relying on that context alone or adding a credential-based
308+
publisher. Require branches to be up to date before merge (or use an equivalent
309+
merge-queue freshness guarantee), and enable the required context only after
310+
the workflow installation is merged and the post-merge Cast canary succeeds.
306311

307312
### 10. Never auto-merge — and explain what comes next
308313

@@ -366,9 +371,8 @@ gh pr edit --add-reviewer @copilot # then wait for review + checks; DO NOT mer
366371
### ✓ Correct: STOP on an undocumented safe-update entry
367372

368373
```text
369-
gh aw add reports an additional secret: `ACME_DEPLOY_KEY`.
370-
→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN,
371-
SQUAD_REVIEW_APP_PRIVATE_KEY)
374+
gh aw add reports a third secret: `ACME_DEPLOY_KEY`.
375+
→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN)
372376
and is NOT the squad-init action. Do NOT run `--approve`.
373377
Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait.
374378
```
@@ -402,8 +406,7 @@ gh pr merge --squash # auto-merge before human review. NEVER.
402406
- ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only
403407
`.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path.
404408
- ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`,
405-
`SQUAD_GITHUB_TOKEN`, `SQUAD_REVIEW_APP_PRIVATE_KEY`, and
406-
`bradygaster/squad/.github/actions/squad-init`. Anything
409+
`SQUAD_GITHUB_TOKEN`, and `bradygaster/squad/.github/actions/squad-init`. Anything
407410
else is a STOP.
408411
- ❌ **Treating `--approve` as the final compile.** Always finish with a plain
409412
`gh aw compile --strict` (no `--approve`).

‎docs/src/content/docs/guide/gh-aw.md‎

Lines changed: 50 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,9 @@ GitHub Actions bot comment, so editable PR prose cannot rebind an old bootstrap
119119
run to a changed branch head. Only after that base-controlled canary succeeds
120120
should the Cast/bootstrap lifecycle be treated as trusted. Do not enable the
121121
required 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

123126
Step 2 deliberately checks Issues before creating the bootstrap branch or
124127
installing any workflow. Squad commands are issue comments, and the merged
@@ -298,21 +301,17 @@ source/lock pairs, and one coherent 40-character revision.
298301

299302
On 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
317316
Review the report before approving it. If it contains only those documented
318317
entries, 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
15571515
The trusted writer publishes these logical verdicts in a native `COMMENT`
15581516
review: 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
15671534
The reviewer has no file-editing, issue-creation,
15681535
pull-request-creation, remediation, merge, or `APPROVE` authority. Its verdict
@@ -1576,9 +1543,9 @@ The lifecycle is:
15761543
```
15771544
15781545
The 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.
15821549
Bypassing a missing Squad review at merge
15831550
cannot silently advance the epic. Missing evidence stops the run with an explicit
15841551
error; it never dispatches the next wave.
@@ -1588,29 +1555,38 @@ error; it never dispatches the next wave.
15881555
The stable literal check name is **`Squad Review / review`**.
15891556
There is no manual reviewer run. `/squad review` only explains how to rerun the
15901557
existing 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
15941561
Brady (or the consumer repository administrator) must install/merge the complete
15951562
generated bundle through the explicit human installation boundary, then observe
15961563
a successful base-controlled `pull_request_target` check on the post-install
15971564
draft Cast PR before
15981565
changing 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
16081570
evidence gate in #1734; promote to `main` after the agreed soak. This change
16091571
does not modify repository rulesets and does not claim live soak evidence. Keep
16101572
native 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.
16141590
Because rulesets apply to all PRs, existing human/Copilot PRs must add committed
16151591
attribution before enabling the requirement. Fork review remains unsupported;
16161592
the workflow rejects foreign head repositories even though its base-controlled

0 commit comments

Comments
 (0)