Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .changeset/dedicated-review-app.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
"@bradygaster/squad-cli": patch
"@bradygaster/squad-sdk": patch
---

Require a dedicated, branch-restricted GitHub App identity for authoritative Squad review checks.
8 changes: 8 additions & 0 deletions .github/agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,14 @@ GitHub Agentic Workflows (`gh-aw`) are composable AI workflows triggered by slas
> Stop at the bootstrap PR; the human merges it.
> `/squad` slash commands become active only after that merge reaches
> the repository's default branch.
> The installation PR is a manual trust boundary: its PR-controlled workflow
> cannot mint a trusted Squad verdict. After merge, require the automatically
> opened Cast PR to pass the exact-head `Squad Review / review` attestation from
> the base-controlled `pull_request_target` authority before treating bootstrap
> or lifecycle automation as trusted. That check must be published by a
> dedicated GitHub App token minted only inside the exact-default-branch
> `squad-review-authority` environment. Missing or misconfigured reviewer
> credentials fail closed; the workflow never falls back to `github.token`.

The quick start installs this workflow set:

Expand Down
9 changes: 7 additions & 2 deletions .github/workflows/squad-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,7 @@ jobs:
# than skipping — a skipped gate is indistinguishable from no gate. This
# includes the shell input security contract gate (#1834) and the compile
# contract (#1732).
run: gh extension install --pin v0.87.10 github/gh-aw
run: gh extension install --pin v0.89.21 github/gh-aw
env:
GH_TOKEN: ${{ github.token }}
- name: Build
Expand Down Expand Up @@ -778,7 +778,12 @@ jobs:
git -C "$CONSUMER_DIR" remote add origin https://github.com/example/squad-consumer.git
(
cd "$CONSUMER_DIR"
gh aw add "$GITHUB_WORKSPACE/workflows"
mkdir -p .github/workflows
for workflow in squad squad-implement-worker squad-review squad-deps-worker squad-retro squad-improvement-worker squad-bootstrap squad-command-router; do
cp "$GITHUB_WORKSPACE/workflows/package/${workflow}.md" \
".github/workflows/${workflow}.md"
done
gh aw add --force "$GITHUB_WORKSPACE/workflows"
node .github/workflows/shared/squad-install-verifier.mjs \
--write-local-test-ownership \
--source-revision "$SQUAD_SOURCE_REVISION"
Expand Down
46 changes: 34 additions & 12 deletions .squad-templates/skills/gh-aw-enlistment/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -182,17 +182,17 @@ uses a moving branch reference.
On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**:

<!-- allowlist-start -->
- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`**
- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`**,
**`SQUAD_GITHUB_TOKEN`**, and **`SQUAD_REVIEW_APP_PRIVATE_KEY`**
- Action: **`bradygaster/squad/.github/actions/squad-init`**
<!-- allowlist-end -->

> **These are referenced names, not prerequisites.** `gh aw add` lists the secrets
> the workflows *reference* so you can approve that surface — it is not asking you
> to supply them. Both secrets are optional, they need not exist, and neither is
> required to enlist a repository. Single-repo activation runs on the built-in
> `github.token`. Configure them only for cross-repo access or elevated
> permissions. Auth precedence: GitHub App token, then the PAT, then
> `github.token`. Never block an enlistment waiting for a credential.
> **Compilation approval is not credential provisioning.** `gh aw add` lists
> referenced names so you can approve the surface. `SQUAD_GITHUB_APP_PRIVATE_KEY`
> and `SQUAD_GITHUB_TOKEN` remain optional activation credentials.
> `SQUAD_REVIEW_APP_PRIVATE_KEY` is different: trusted check publication requires
> it in the exact-default-branch `squad-review-authority` environment. Never put
> reviewer credentials at repository scope and never fall back to `github.token`.

If — and only if — the report contains exactly those documented entries, complete
the one-time approval:
Expand Down Expand Up @@ -284,7 +284,27 @@ gh pr checks --watch
`main`.
- Request Copilot review, address feedback, and wait for required checks.

### 9. Never auto-merge — and explain what comes next
### 9. Verify the external review-authority prerequisite when API access permits

Before claiming trusted review is ready, query the repository environment. It
must be named `squad-review-authority`, use custom deployment branch policies,
allow exactly the captured `${default_branch}`, contain the environment secret
`SQUAD_REVIEW_APP_PRIVATE_KEY`, and define environment variables
`SQUAD_REVIEW_APP_ID`, `SQUAD_REVIEW_APP_SLUG`, and
`SQUAD_REVIEW_APP_OWNER`. The App ID/slug must differ from
`15368`/`github-actions`. All four reviewer-specific names must also be absent
from repository-level Actions secrets and variables; repository fallback does
not satisfy this gate.

If the authenticated account cannot read environment configuration, or any
requirement is absent, report the exact external prerequisite and do not claim
the required check is trusted. The installation PR remains a human boundary;
after it merges, the Cast canary intentionally fails closed until an
administrator provisions the environment and reruns the base-controlled
review. Configure a ruleset only from the canary check's observed App
integration ID, never from user input or a guessed value.

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

- **Never** merge the bootstrap PR yourself. Merge happens **only** after human
approval.
Expand Down Expand Up @@ -346,8 +366,9 @@ gh pr edit --add-reviewer @copilot # then wait for review + checks; DO NOT mer
### ✓ Correct: STOP on an undocumented safe-update entry

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