From 0747964ca4cfc13a4b1c3e97d09673a581094909 Mon Sep 17 00:00:00 2001 From: Copilot Date: Mon, 9 Nov 2026 15:50:11 +0200 Subject: [PATCH 1/2] fix(gh-aw): preserve Windows/XDG gh extension env in verifier and align quickstart safe-update docs - Preserve APPDATA, GH_DATA_DIR, LOCALAPPDATA, SystemRoot, TEMP, TMP, USERPROFILE, XDG_CONFIG_HOME, and XDG_DATA_HOME in squad-install-verifier.mjs spawnChecked() so strict-compile on Windows finds the pinned gh-aw extension instead of falling back to an unpinned install. - Update the first-install safe-update allowlist in the GH-AW guide and gh-aw-enlistment skill to include GH_AW_GITHUB_READ_APP_PRIVATE_KEY alongside SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN, and github/squad/.github/actions/squad-init. - Scope preflight gh auth status to --hostname github.com so multi-host setups do not fail under set -euo pipefail. - Refresh workflows/squad-workflows.manifest.json and embedded verifier digests. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../skills/gh-aw-enlistment/SKILL.md | 22 ++++++------- docs/src/content/docs/guide/gh-aw.md | 18 ++++++----- .../skills/gh-aw-enlistment/SKILL.md | 22 ++++++------- .../skills/gh-aw-enlistment/SKILL.md | 22 ++++++------- templates/skills/gh-aw-enlistment/SKILL.md | 22 ++++++------- test/gh-aw-enlistment-skill.test.ts | 31 ++++++++++++++++--- workflows/package/squad-bootstrap.md | 2 +- workflows/shared/squad-install-verifier.mjs | 25 ++++++++++++++- workflows/skills/gh-aw-enlistment/SKILL.md | 22 ++++++------- workflows/squad-bootstrap.md | 2 +- workflows/squad-workflows.manifest.json | 14 ++++----- 11 files changed, 125 insertions(+), 77 deletions(-) diff --git a/.squad-templates/skills/gh-aw-enlistment/SKILL.md b/.squad-templates/skills/gh-aw-enlistment/SKILL.md index 3fafef0ff..969430759 100644 --- a/.squad-templates/skills/gh-aw-enlistment/SKILL.md +++ b/.squad-templates/skills/gh-aw-enlistment/SKILL.md @@ -51,8 +51,8 @@ condition and wait for a human decision — do not work around it. ### 0. Preflight — verify before you touch anything ```bash -# gh is authenticated -gh auth status +# gh is authenticated on github.com +gh auth status --hostname github.com # Prove the exact package-capable compiler version before creating artifacts # gh-aw-exact-version-start @@ -92,7 +92,7 @@ git status --short > streams again. Stop before branch creation or file generation unless that > second check proves exactly `v0.91.5`; never select a newer release. -- **STOP** if `gh auth status` is not logged in, or is logged in as the wrong +- **STOP** if `gh auth status --hostname github.com` is not logged in, or is logged in as the wrong identity for this repo (see the `gh-auth-isolation` skill to operate as a specific account without switching the global default). - **STOP** if `owner_repo` or `default_branch` cannot be resolved. @@ -329,16 +329,16 @@ already-approved revision. On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**: -- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`** +- Restricted secrets: **`GH_AW_GITHUB_READ_APP_PRIVATE_KEY`**, **`SQUAD_GITHUB_APP_PRIVATE_KEY`**, and **`SQUAD_GITHUB_TOKEN`** - Action: **`github/squad/.github/actions/squad-init`** > **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 +> to supply them. All three secrets are optional, they need not exist, and none 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`. Configure them only for cross-repo access, elevated +> permissions, or optional CAO evidence collection. Auth precedence: GitHub App token, then the PAT, then > `github.token`. Never block an enlistment waiting for a credential. If — and only if — the report contains exactly those documented entries, complete @@ -657,7 +657,7 @@ test "${squad_package}" = "github/squad/workflows" || { gh aw add "github/squad/workflows@${SQUAD_SHA}" rm -f .github/skills/agentic-workflows/SKILL.md -# Safe-update report shows ONLY the two documented secrets + squad-init → approve once +# Safe-update report shows ONLY the three documented secrets + squad-init → approve once gh aw compile --strict --approve node .github/workflows/shared/squad-install-verifier.mjs --materialize-runtime gh aw compile --strict # final, no --approve; exactly the two documented warnings remain @@ -684,8 +684,8 @@ gh api graphql -f query=' ### ✓ 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 undocumented secret: `ACME_DEPLOY_KEY`. +→ This is NOT in the allowlist (GH_AW_GITHUB_READ_APP_PRIVATE_KEY, SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) and is NOT the squad-init action. Do NOT run `--approve`. Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait. ``` @@ -721,7 +721,7 @@ gh pr merge --squash # auto-merge before human review. NEVER. - ❌ **Committing gh-aw's mutable router.** Remove only `.github/skills/agentic-workflows/SKILL.md`; keep the exact Squad-owned `.github/skills/gh-aw-enlistment/SKILL.md`. -- ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`, +- ❌ **Approving unknown safe updates.** Approve ONLY `GH_AW_GITHUB_READ_APP_PRIVATE_KEY`, `SQUAD_GITHUB_APP_PRIVATE_KEY`, `SQUAD_GITHUB_TOKEN`, and `github/squad/.github/actions/squad-init`. Anything else is a STOP. - ❌ **Treating `--approve` as the final compile.** Always finish with a plain diff --git a/docs/src/content/docs/guide/gh-aw.md b/docs/src/content/docs/guide/gh-aw.md index 224b8f2fb..feda72fa1 100644 --- a/docs/src/content/docs/guide/gh-aw.md +++ b/docs/src/content/docs/guide/gh-aw.md @@ -38,7 +38,7 @@ Seven steps from zero to a validated, reviewable Squad bootstrap: set -euo pipefail # 1. Verify GitHub access and prove the exact supported gh-aw version -gh auth status +gh auth status --hostname github.com # gh-aw-exact-version-start required_gh_aw_version="v0.91.5" @@ -132,8 +132,8 @@ gh aw add "github/squad/workflows@${SQUAD_SHA}" rm -f .github/skills/agentic-workflows/SKILL.md # 5. On first install, review the safe-update report. Approve ONLY if it -# contains exactly the two documented secrets (SQUAD_GITHUB_APP_PRIVATE_KEY, -# SQUAD_GITHUB_TOKEN) and the one documented action +# contains exactly the three documented secrets (GH_AW_GITHUB_READ_APP_PRIVATE_KEY, +# SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) and the one documented action # (github/squad/.github/actions/squad-init) and nothing else. STOP and # report any other entry instead of approving. gh aw compile --strict --approve # first install only, when the safe-update warning appears @@ -241,7 +241,9 @@ that update fails, stop before installation and ask an administrator to enable > Step 7 stages `.github/skills/` because `gh aw add` installs the Squad skill > alongside the workflows and may need to stage deletion of gh-aw's unowned > `.github/skills/agentic-workflows/SKILL.md`. It deliberately does not stage -> `.github/aw/logs/`. +> `.github/aw/logs/` or `.vscode/settings.json` (which `gh aw add` may create as +> an optional local editor setting — delete it if unwanted or stage it +> explicitly if your team wants to share it). > Downloaded workflow logs are local diagnostic output — see [ignoring downloaded > logs](#open-the-bootstrap-pull-request) before you commit. @@ -695,15 +697,15 @@ source/lock pairs, and one coherent 40-character revision. On a clean repository, `gh aw add` reports these expected safe-update changes: -- Restricted secrets: `SQUAD_GITHUB_APP_PRIVATE_KEY` and `SQUAD_GITHUB_TOKEN` +- Restricted secrets: `GH_AW_GITHUB_READ_APP_PRIVATE_KEY`, `SQUAD_GITHUB_APP_PRIVATE_KEY`, and `SQUAD_GITHUB_TOKEN` - Action: `github/squad/.github/actions/squad-init` > **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 you do not -> need to create either one to enlist a repository. Single-repo activation runs on +> to supply them. All three secrets are optional, they need not exist, and you do not +> need to create any of them to enlist a repository. Single-repo activation runs on > the built-in `github.token`. Configure these only for an explicit alternative -> activation identity — see [activation credentials with a GitHub +> activation identity or optional CAO evidence collection — see [activation credentials with a GitHub > App](#optional-activation-credentials-with-a-github-app) and [PAT > fallback](#optional-pat-fallback). diff --git a/packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md b/packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md index 3fafef0ff..969430759 100644 --- a/packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md +++ b/packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md @@ -51,8 +51,8 @@ condition and wait for a human decision — do not work around it. ### 0. Preflight — verify before you touch anything ```bash -# gh is authenticated -gh auth status +# gh is authenticated on github.com +gh auth status --hostname github.com # Prove the exact package-capable compiler version before creating artifacts # gh-aw-exact-version-start @@ -92,7 +92,7 @@ git status --short > streams again. Stop before branch creation or file generation unless that > second check proves exactly `v0.91.5`; never select a newer release. -- **STOP** if `gh auth status` is not logged in, or is logged in as the wrong +- **STOP** if `gh auth status --hostname github.com` is not logged in, or is logged in as the wrong identity for this repo (see the `gh-auth-isolation` skill to operate as a specific account without switching the global default). - **STOP** if `owner_repo` or `default_branch` cannot be resolved. @@ -329,16 +329,16 @@ already-approved revision. On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**: -- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`** +- Restricted secrets: **`GH_AW_GITHUB_READ_APP_PRIVATE_KEY`**, **`SQUAD_GITHUB_APP_PRIVATE_KEY`**, and **`SQUAD_GITHUB_TOKEN`** - Action: **`github/squad/.github/actions/squad-init`** > **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 +> to supply them. All three secrets are optional, they need not exist, and none 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`. Configure them only for cross-repo access, elevated +> permissions, or optional CAO evidence collection. Auth precedence: GitHub App token, then the PAT, then > `github.token`. Never block an enlistment waiting for a credential. If — and only if — the report contains exactly those documented entries, complete @@ -657,7 +657,7 @@ test "${squad_package}" = "github/squad/workflows" || { gh aw add "github/squad/workflows@${SQUAD_SHA}" rm -f .github/skills/agentic-workflows/SKILL.md -# Safe-update report shows ONLY the two documented secrets + squad-init → approve once +# Safe-update report shows ONLY the three documented secrets + squad-init → approve once gh aw compile --strict --approve node .github/workflows/shared/squad-install-verifier.mjs --materialize-runtime gh aw compile --strict # final, no --approve; exactly the two documented warnings remain @@ -684,8 +684,8 @@ gh api graphql -f query=' ### ✓ 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 undocumented secret: `ACME_DEPLOY_KEY`. +→ This is NOT in the allowlist (GH_AW_GITHUB_READ_APP_PRIVATE_KEY, SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) and is NOT the squad-init action. Do NOT run `--approve`. Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait. ``` @@ -721,7 +721,7 @@ gh pr merge --squash # auto-merge before human review. NEVER. - ❌ **Committing gh-aw's mutable router.** Remove only `.github/skills/agentic-workflows/SKILL.md`; keep the exact Squad-owned `.github/skills/gh-aw-enlistment/SKILL.md`. -- ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`, +- ❌ **Approving unknown safe updates.** Approve ONLY `GH_AW_GITHUB_READ_APP_PRIVATE_KEY`, `SQUAD_GITHUB_APP_PRIVATE_KEY`, `SQUAD_GITHUB_TOKEN`, and `github/squad/.github/actions/squad-init`. Anything else is a STOP. - ❌ **Treating `--approve` as the final compile.** Always finish with a plain diff --git a/packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md b/packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md index 3fafef0ff..969430759 100644 --- a/packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md +++ b/packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md @@ -51,8 +51,8 @@ condition and wait for a human decision — do not work around it. ### 0. Preflight — verify before you touch anything ```bash -# gh is authenticated -gh auth status +# gh is authenticated on github.com +gh auth status --hostname github.com # Prove the exact package-capable compiler version before creating artifacts # gh-aw-exact-version-start @@ -92,7 +92,7 @@ git status --short > streams again. Stop before branch creation or file generation unless that > second check proves exactly `v0.91.5`; never select a newer release. -- **STOP** if `gh auth status` is not logged in, or is logged in as the wrong +- **STOP** if `gh auth status --hostname github.com` is not logged in, or is logged in as the wrong identity for this repo (see the `gh-auth-isolation` skill to operate as a specific account without switching the global default). - **STOP** if `owner_repo` or `default_branch` cannot be resolved. @@ -329,16 +329,16 @@ already-approved revision. On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**: -- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`** +- Restricted secrets: **`GH_AW_GITHUB_READ_APP_PRIVATE_KEY`**, **`SQUAD_GITHUB_APP_PRIVATE_KEY`**, and **`SQUAD_GITHUB_TOKEN`** - Action: **`github/squad/.github/actions/squad-init`** > **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 +> to supply them. All three secrets are optional, they need not exist, and none 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`. Configure them only for cross-repo access, elevated +> permissions, or optional CAO evidence collection. Auth precedence: GitHub App token, then the PAT, then > `github.token`. Never block an enlistment waiting for a credential. If — and only if — the report contains exactly those documented entries, complete @@ -657,7 +657,7 @@ test "${squad_package}" = "github/squad/workflows" || { gh aw add "github/squad/workflows@${SQUAD_SHA}" rm -f .github/skills/agentic-workflows/SKILL.md -# Safe-update report shows ONLY the two documented secrets + squad-init → approve once +# Safe-update report shows ONLY the three documented secrets + squad-init → approve once gh aw compile --strict --approve node .github/workflows/shared/squad-install-verifier.mjs --materialize-runtime gh aw compile --strict # final, no --approve; exactly the two documented warnings remain @@ -684,8 +684,8 @@ gh api graphql -f query=' ### ✓ 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 undocumented secret: `ACME_DEPLOY_KEY`. +→ This is NOT in the allowlist (GH_AW_GITHUB_READ_APP_PRIVATE_KEY, SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) and is NOT the squad-init action. Do NOT run `--approve`. Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait. ``` @@ -721,7 +721,7 @@ gh pr merge --squash # auto-merge before human review. NEVER. - ❌ **Committing gh-aw's mutable router.** Remove only `.github/skills/agentic-workflows/SKILL.md`; keep the exact Squad-owned `.github/skills/gh-aw-enlistment/SKILL.md`. -- ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`, +- ❌ **Approving unknown safe updates.** Approve ONLY `GH_AW_GITHUB_READ_APP_PRIVATE_KEY`, `SQUAD_GITHUB_APP_PRIVATE_KEY`, `SQUAD_GITHUB_TOKEN`, and `github/squad/.github/actions/squad-init`. Anything else is a STOP. - ❌ **Treating `--approve` as the final compile.** Always finish with a plain diff --git a/templates/skills/gh-aw-enlistment/SKILL.md b/templates/skills/gh-aw-enlistment/SKILL.md index 3fafef0ff..969430759 100644 --- a/templates/skills/gh-aw-enlistment/SKILL.md +++ b/templates/skills/gh-aw-enlistment/SKILL.md @@ -51,8 +51,8 @@ condition and wait for a human decision — do not work around it. ### 0. Preflight — verify before you touch anything ```bash -# gh is authenticated -gh auth status +# gh is authenticated on github.com +gh auth status --hostname github.com # Prove the exact package-capable compiler version before creating artifacts # gh-aw-exact-version-start @@ -92,7 +92,7 @@ git status --short > streams again. Stop before branch creation or file generation unless that > second check proves exactly `v0.91.5`; never select a newer release. -- **STOP** if `gh auth status` is not logged in, or is logged in as the wrong +- **STOP** if `gh auth status --hostname github.com` is not logged in, or is logged in as the wrong identity for this repo (see the `gh-auth-isolation` skill to operate as a specific account without switching the global default). - **STOP** if `owner_repo` or `default_branch` cannot be resolved. @@ -329,16 +329,16 @@ already-approved revision. On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**: -- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`** +- Restricted secrets: **`GH_AW_GITHUB_READ_APP_PRIVATE_KEY`**, **`SQUAD_GITHUB_APP_PRIVATE_KEY`**, and **`SQUAD_GITHUB_TOKEN`** - Action: **`github/squad/.github/actions/squad-init`** > **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 +> to supply them. All three secrets are optional, they need not exist, and none 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`. Configure them only for cross-repo access, elevated +> permissions, or optional CAO evidence collection. Auth precedence: GitHub App token, then the PAT, then > `github.token`. Never block an enlistment waiting for a credential. If — and only if — the report contains exactly those documented entries, complete @@ -657,7 +657,7 @@ test "${squad_package}" = "github/squad/workflows" || { gh aw add "github/squad/workflows@${SQUAD_SHA}" rm -f .github/skills/agentic-workflows/SKILL.md -# Safe-update report shows ONLY the two documented secrets + squad-init → approve once +# Safe-update report shows ONLY the three documented secrets + squad-init → approve once gh aw compile --strict --approve node .github/workflows/shared/squad-install-verifier.mjs --materialize-runtime gh aw compile --strict # final, no --approve; exactly the two documented warnings remain @@ -684,8 +684,8 @@ gh api graphql -f query=' ### ✓ 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 undocumented secret: `ACME_DEPLOY_KEY`. +→ This is NOT in the allowlist (GH_AW_GITHUB_READ_APP_PRIVATE_KEY, SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) and is NOT the squad-init action. Do NOT run `--approve`. Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait. ``` @@ -721,7 +721,7 @@ gh pr merge --squash # auto-merge before human review. NEVER. - ❌ **Committing gh-aw's mutable router.** Remove only `.github/skills/agentic-workflows/SKILL.md`; keep the exact Squad-owned `.github/skills/gh-aw-enlistment/SKILL.md`. -- ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`, +- ❌ **Approving unknown safe updates.** Approve ONLY `GH_AW_GITHUB_READ_APP_PRIVATE_KEY`, `SQUAD_GITHUB_APP_PRIVATE_KEY`, `SQUAD_GITHUB_TOKEN`, and `github/squad/.github/actions/squad-init`. Anything else is a STOP. - ❌ **Treating `--approve` as the final compile.** Always finish with a plain diff --git a/test/gh-aw-enlistment-skill.test.ts b/test/gh-aw-enlistment-skill.test.ts index 1cc071f76..a72d52fd7 100644 --- a/test/gh-aw-enlistment-skill.test.ts +++ b/test/gh-aw-enlistment-skill.test.ts @@ -29,6 +29,7 @@ import { LEGACY_PACKAGE_NAMES, OWNERSHIP_DESTINATION, PACKAGE_NAME, + SAFE_ENVIRONMENT_KEYS, UNOWNED_MUTABLE_ROUTER_SKILL, WORKFLOW_TUPLES, compileWithPinnedActions, @@ -842,7 +843,7 @@ describe('gh-aw-enlistment skill', () => { expect(endMatches.length, ' must appear exactly once').toBe(1); }); - it('allowlist region contains EXACTLY the two documented secrets and the one documented action — no more, no fewer', () => { + it('allowlist region contains EXACTLY the three documented secrets and the one documented action — no more, no fewer', () => { const startTag = ''; const endTag = ''; const startIdx = content.indexOf(startTag); @@ -855,15 +856,16 @@ describe('gh-aw-enlistment skill', () => { // Every backtick-delimited token in the region — order-independent exact set. const tokens = [...region.matchAll(/`([^`]+)`/g)].map(m => m[1]); - expect(tokens.slice().sort(), 'allowlist tokens must be exactly the three documented entries').toEqual( + expect(tokens.slice().sort(), 'allowlist tokens must be exactly the four documented entries').toEqual( [ + 'GH_AW_GITHUB_READ_APP_PRIVATE_KEY', 'SQUAD_GITHUB_APP_PRIVATE_KEY', 'SQUAD_GITHUB_TOKEN', SQUAD_INIT_ACTION, ].sort() ); - // Structural: exactly 2 bullet lines (one for the two secrets, one for the action). + // Structural: exactly 2 bullet lines (one for the three secrets, one for the action). const bulletLines = region.split('\n').filter(l => l.trimStart().startsWith('- ')); expect(bulletLines.length, 'allowlist region must contain exactly 2 bullet lines').toBe(2); }); @@ -1124,7 +1126,7 @@ describe('gh-aw-enlistment skill', () => { .not.toContain(LEGACY_SQUAD_INIT_ACTION); } expect(antiPatterns.replace(/\s+/g, ' ')).toContain( - `Approve ONLY \`SQUAD_GITHUB_APP_PRIVATE_KEY\`, \`SQUAD_GITHUB_TOKEN\`, and \`${SQUAD_INIT_ACTION}\`. ` + `Approve ONLY \`GH_AW_GITHUB_READ_APP_PRIVATE_KEY\`, \`SQUAD_GITHUB_APP_PRIVATE_KEY\`, \`SQUAD_GITHUB_TOKEN\`, and \`${SQUAD_INIT_ACTION}\`. ` + 'Anything else is a STOP.', ); }); @@ -1214,10 +1216,29 @@ describe('gh-aw-enlistment skill', () => { }); it('resolves repo identity at runtime (no hardcoded owner/repo placeholder)', () => { + expect(content).toContain('gh auth status --hostname github.com'); expect(content).toContain('gh repo view --json nameWithOwner'); expect(content).toContain('gh repo view --json defaultBranchRef'); }); + it('preserves Windows and XDG gh extension environment variables in squad-install-verifier spawnChecked', () => { + for (const envKey of [ + 'APPDATA', + 'GH_CONFIG_DIR', + 'GH_DATA_DIR', + 'LOCALAPPDATA', + 'SystemRoot', + 'TEMP', + 'TMP', + 'USERPROFILE', + 'XDG_CONFIG_HOME', + 'XDG_DATA_HOME', + ]) { + expect(SAFE_ENVIRONMENT_KEYS, `SAFE_ENVIRONMENT_KEYS must preserve ${envKey}`).toContain(envKey); + } + expect(Object.isFrozen(SAFE_ENVIRONMENT_KEYS)).toBe(true); + }); + it('names the bootstrap job\'s own PR-creation fallback branch as the real Cast branch, distinct from the human-run install branch', () => { // Regression for a Copilot review finding: this paragraph explains what // happens when the *automated* bootstrap workflow's own @@ -1332,6 +1353,8 @@ describe('gh-aw-enlistment skill', () => { .not.toContain(LEGACY_INSTALL_PREFIX); } } + expect(guide).toContain('gh auth status --hostname github.com'); + expect(guide).toContain('GH_AW_GITHUB_READ_APP_PRIVATE_KEY'); expect(guide).toContain(`# (${SQUAD_INIT_ACTION}) and nothing else. STOP and`); expect(guide).toContain(`- Action: \`${SQUAD_INIT_ACTION}\``); expect(guide.replace(/\s+/g, ' '), `${GUIDE} must not offer ${LEGACY_SQUAD_INIT_ACTION} as a referenced name`) diff --git a/workflows/package/squad-bootstrap.md b/workflows/package/squad-bootstrap.md index 9d8c274f7..c7cbafa0f 100644 --- a/workflows/package/squad-bootstrap.md +++ b/workflows/package/squad-bootstrap.md @@ -153,7 +153,7 @@ pre-agent-steps: node --check "$path" >/dev/null } # BEGIN GENERATED RESOURCE DIGESTS - check_hash "$install_verifier" "514683e50c87644a1bf3977727f84e7bece7a94afc1f5ff5b5cf4c5e3ec2b77e" + check_hash "$install_verifier" "b3d02414a2b4daa5f868f881954317feee5266988e2930006aab8ddc69f7c69d" check_hash "$cast_validator" "15f0d47917d269b5b967dc2a782a0eb761c39af7a92ddb64fed687a427070760" check_hash "$bootstrap_validator" "d552d041f006249bfaa67b10a75877f813796b7698c718ac7eb7cf16f3a72e31" # END GENERATED RESOURCE DIGESTS diff --git a/workflows/shared/squad-install-verifier.mjs b/workflows/shared/squad-install-verifier.mjs index 287d0ec68..8a172d4ad 100644 --- a/workflows/shared/squad-install-verifier.mjs +++ b/workflows/shared/squad-install-verifier.mjs @@ -1052,9 +1052,32 @@ function strictCompileMatches(root) { } } +export const SAFE_ENVIRONMENT_KEYS = Object.freeze([ + 'APPDATA', + 'CI', + 'GH_CONFIG_DIR', + 'GH_DATA_DIR', + 'GH_HOST', + 'HOME', + 'LANG', + 'LC_ALL', + 'LOCALAPPDATA', + 'NO_COLOR', + 'PATH', + 'SHELL', + 'SystemRoot', + 'TEMP', + 'TERM', + 'TMP', + 'TMPDIR', + 'USERPROFILE', + 'XDG_CONFIG_HOME', + 'XDG_DATA_HOME', +]); + function spawnChecked(command, args, cwd, options = {}) { const safeEnvironment = Object.fromEntries( - ['CI', 'GH_CONFIG_DIR', 'GH_HOST', 'HOME', 'LANG', 'LC_ALL', 'NO_COLOR', 'PATH', 'SHELL', 'TERM', 'TMPDIR'] + SAFE_ENVIRONMENT_KEYS .filter((key) => process.env[key] !== undefined) .map((key) => [key, process.env[key]]), ); diff --git a/workflows/skills/gh-aw-enlistment/SKILL.md b/workflows/skills/gh-aw-enlistment/SKILL.md index 3fafef0ff..969430759 100644 --- a/workflows/skills/gh-aw-enlistment/SKILL.md +++ b/workflows/skills/gh-aw-enlistment/SKILL.md @@ -51,8 +51,8 @@ condition and wait for a human decision — do not work around it. ### 0. Preflight — verify before you touch anything ```bash -# gh is authenticated -gh auth status +# gh is authenticated on github.com +gh auth status --hostname github.com # Prove the exact package-capable compiler version before creating artifacts # gh-aw-exact-version-start @@ -92,7 +92,7 @@ git status --short > streams again. Stop before branch creation or file generation unless that > second check proves exactly `v0.91.5`; never select a newer release. -- **STOP** if `gh auth status` is not logged in, or is logged in as the wrong +- **STOP** if `gh auth status --hostname github.com` is not logged in, or is logged in as the wrong identity for this repo (see the `gh-auth-isolation` skill to operate as a specific account without switching the global default). - **STOP** if `owner_repo` or `default_branch` cannot be resolved. @@ -329,16 +329,16 @@ already-approved revision. On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**: -- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`** +- Restricted secrets: **`GH_AW_GITHUB_READ_APP_PRIVATE_KEY`**, **`SQUAD_GITHUB_APP_PRIVATE_KEY`**, and **`SQUAD_GITHUB_TOKEN`** - Action: **`github/squad/.github/actions/squad-init`** > **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 +> to supply them. All three secrets are optional, they need not exist, and none 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`. Configure them only for cross-repo access, elevated +> permissions, or optional CAO evidence collection. Auth precedence: GitHub App token, then the PAT, then > `github.token`. Never block an enlistment waiting for a credential. If — and only if — the report contains exactly those documented entries, complete @@ -657,7 +657,7 @@ test "${squad_package}" = "github/squad/workflows" || { gh aw add "github/squad/workflows@${SQUAD_SHA}" rm -f .github/skills/agentic-workflows/SKILL.md -# Safe-update report shows ONLY the two documented secrets + squad-init → approve once +# Safe-update report shows ONLY the three documented secrets + squad-init → approve once gh aw compile --strict --approve node .github/workflows/shared/squad-install-verifier.mjs --materialize-runtime gh aw compile --strict # final, no --approve; exactly the two documented warnings remain @@ -684,8 +684,8 @@ gh api graphql -f query=' ### ✓ 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 undocumented secret: `ACME_DEPLOY_KEY`. +→ This is NOT in the allowlist (GH_AW_GITHUB_READ_APP_PRIVATE_KEY, SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) and is NOT the squad-init action. Do NOT run `--approve`. Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait. ``` @@ -721,7 +721,7 @@ gh pr merge --squash # auto-merge before human review. NEVER. - ❌ **Committing gh-aw's mutable router.** Remove only `.github/skills/agentic-workflows/SKILL.md`; keep the exact Squad-owned `.github/skills/gh-aw-enlistment/SKILL.md`. -- ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`, +- ❌ **Approving unknown safe updates.** Approve ONLY `GH_AW_GITHUB_READ_APP_PRIVATE_KEY`, `SQUAD_GITHUB_APP_PRIVATE_KEY`, `SQUAD_GITHUB_TOKEN`, and `github/squad/.github/actions/squad-init`. Anything else is a STOP. - ❌ **Treating `--approve` as the final compile.** Always finish with a plain diff --git a/workflows/squad-bootstrap.md b/workflows/squad-bootstrap.md index 708fe938f..d73217fec 100644 --- a/workflows/squad-bootstrap.md +++ b/workflows/squad-bootstrap.md @@ -160,7 +160,7 @@ pre-agent-steps: node --check "$path" >/dev/null } # BEGIN GENERATED RESOURCE DIGESTS - check_hash "$install_verifier" "514683e50c87644a1bf3977727f84e7bece7a94afc1f5ff5b5cf4c5e3ec2b77e" + check_hash "$install_verifier" "b3d02414a2b4daa5f868f881954317feee5266988e2930006aab8ddc69f7c69d" check_hash "$cast_validator" "15f0d47917d269b5b967dc2a782a0eb761c39af7a92ddb64fed687a427070760" check_hash "$bootstrap_validator" "d552d041f006249bfaa67b10a75877f813796b7698c718ac7eb7cf16f3a72e31" # END GENERATED RESOURCE DIGESTS diff --git a/workflows/squad-workflows.manifest.json b/workflows/squad-workflows.manifest.json index 95baf1d7a..de3df5c09 100644 --- a/workflows/squad-workflows.manifest.json +++ b/workflows/squad-workflows.manifest.json @@ -69,9 +69,9 @@ "source": "workflows/package/squad-bootstrap.md", "destination": ".github/workflows/squad-bootstrap.md", "lock": ".github/workflows/squad-bootstrap.lock.yml", - "source_sha256": "fe92a3c7a4402f3f57cf1e041fb78f11ed62312c919271a931773612eceb87bf", - "lock_sha256": "7a9cb513812da3c43e03d14ba06ecff0375d41b3720e64e0d7937001082fd3d0", - "package_lock_sha256": "a3b20ed0fb1823b56ba82144b39eb020448bb8674ad5aa957781a41be54a00b8" + "source_sha256": "523360c80dc2d5b8fc49c80872f6d9c026a9ddc150fb5093572277679d59e749", + "lock_sha256": "5874e5c1ec3860957e7e8f7609af04b4f98b8b6fd44ac821346d709973cf2f0b", + "package_lock_sha256": "b51f771b2f394af4749e5de50a508229b5844a19d0f988317a79a0cea2bba36e" }, { "name": "squad-command-router", @@ -119,8 +119,8 @@ }, { "name": "squad-bootstrap", - "lock_sha256": "e5fbfe1af46967e453d37aa1222d97704f00cc5e52e39cd2070f7cc7538d4222", - "package_lock_sha256": "507b720abf3ec96106a2f1ab21b2fde6cd1088814f06ea6054f3c58ee7291ef4" + "lock_sha256": "7bc5eceb66a2e1b8da43c2239476a6ca750de56ddeccbd689e94fc0a87da2b40", + "package_lock_sha256": "805a04d1e6e57ef814cbec83993d776c07f2f1bc6b39134daff7aac08087d500" }, { "name": "squad-command-router", @@ -169,7 +169,7 @@ "package_destination": ".github/workflows/shared/squad-install-verifier.mjs", "destination": ".github/workflows/shared/squad-install-verifier.mjs", "ownership": "manifest", - "sha256": "514683e50c87644a1bf3977727f84e7bece7a94afc1f5ff5b5cf4c5e3ec2b77e" + "sha256": "b3d02414a2b4daa5f868f881954317feee5266988e2930006aab8ddc69f7c69d" }, { "path": "shared/squad-command-contract.mjs", @@ -305,7 +305,7 @@ "name": "gh-aw-enlistment", "source": "workflows/skills/gh-aw-enlistment/SKILL.md", "destination": ".github/skills/gh-aw-enlistment/SKILL.md", - "sha256": "a0c3eb2202cf2afdd66e334769c4ce88407d10b7714f86fc869da8efe8c76881" + "sha256": "6fa7ef173f9b121a854e7e923ee11044890658d924bb09c963d8dc78a72a5abf" } ], "bootstrap": { From 4dfd31881c18474fa74ec8080fbdadc63d68d685 Mon Sep 17 00:00:00 2001 From: Copilot Date: Mon, 9 Nov 2026 16:01:01 +0200 Subject: [PATCH 2/2] chore: add changeset for gh-aw verifier and enlistment skill updates Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .changeset/gh-aw-windows-verifier-and-quickstart.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .changeset/gh-aw-windows-verifier-and-quickstart.md diff --git a/.changeset/gh-aw-windows-verifier-and-quickstart.md b/.changeset/gh-aw-windows-verifier-and-quickstart.md new file mode 100644 index 000000000..24a7ee6cf --- /dev/null +++ b/.changeset/gh-aw-windows-verifier-and-quickstart.md @@ -0,0 +1,6 @@ +--- +"@bradygaster/squad-cli": patch +"@bradygaster/squad-sdk": patch +--- + +Preserve Windows and XDG GitHub CLI extension environment variables in squad-install-verifier.mjs and update the gh-aw-enlistment skill and guide for github.com preflight auth and the three first-install safe-update secrets.