[Cross-Squad] Make generated workflow runners and checkout security configurable

Source squad: desharpe/HealthAgent
Request type: cross-repository task delegation
Routing: Booster (CI/CD), with CONTROL/RETRO review
Related: #1493, #1462

Problem

@bradygaster/squad-cli and @bradygaster/squad-sdk currently emit GitHub Actions workflows with hardcoded hosted runners and mutable action tags. CLI upgrade also duplicates non-NPM workflow stubs, so repository-local template hardening is not preserved for standalone/global installs. This blocks downstream repositories that require organization-specific self-hosted runner labels and secure checkout defaults.

HealthAgent confirmed that patching installed package files from postinstall is not an acceptable fix: it is repository-specific, misses standalone/global CLI usage, and can generate the wrong ecosystem workflow.

Requested generic fix

Add shared workflow-generation options supporting scalar or multi-label runs-on values without hardcoding a downstream repository's policy.
Make secure checkout defaults explicit: immutable action references and persist-credentials: false.
Consolidate CLI init/upgrade and non-NPM stubs on the shared generic renderer instead of duplicating workflow YAML generation.
Expose equivalent runner/security options through the public SDK CI generator.
Persist optional workflow-generation configuration in .squad/config.json so squad upgrade can reproduce the intended policy.
Validate configured runner/action values and reject control characters or mutable action references where custom refs are accepted.
Keep generated workflows ecosystem-aware for npm, .NET, Go, Python, Java, and unknown projects.

Acceptance criteria

Fresh init and upgrade from a globally installed CLI honor configured scalar and multi-label runners.
Public SDK generation produces the same runner and checkout-security behavior as the CLI.
Upgrade no longer replaces a configured self-hosted policy with ubuntu-latest.
Generated checkout steps use immutable pins and disable persisted credentials by default.
Generic ecosystem tests cover init, upgrade, standalone/global package behavior, and SDK generation.
CLI and SDK receive changesets and the fix is published on npm.

Downstream dependency: desharpe/HealthAgent#190. HealthAgent will remove its rejected local postinstall patch and upgrade to the published fixed packages before its runner-policy PR can merge.

Owner & rationale

Owner: Booster (squad:booster). This is a workflow-generation policy/configuration problem: emitted GitHub Actions runners and checkout security defaults are hardcoded today. CONTROL and RETRO should review the final design, but Booster should own the CI/CD behavior and verification gate.

Readiness: go:needs-research. The ask is RFC-shaped because it spans CLI templates, CLI upgrade config persistence, SDK CI generation, scheduler-generated workflows, validation rules, and security defaults.

Files in scope

Verified existing paths:

packages/squad-cli/src/cli/core/upgrade.ts
packages/squad-cli/src/cli/core/templates.ts
packages/squad-cli/templates/workflows/squad-ci.yml
packages/squad-cli/templates/workflows/squad-docs.yml
packages/squad-cli/templates/workflows/squad-heartbeat.yml
packages/squad-cli/templates/workflows/squad-insider-release.yml
packages/squad-cli/templates/workflows/squad-issue-assign.yml
packages/squad-cli/templates/workflows/squad-label-enforce.yml
packages/squad-cli/templates/workflows/squad-preview.yml
packages/squad-cli/templates/workflows/squad-promote.yml
packages/squad-cli/templates/workflows/squad-release.yml
packages/squad-cli/templates/workflows/squad-triage.yml
packages/squad-cli/templates/workflows/sync-squad-labels.yml
packages/squad-sdk/src/build/ci-pipeline.ts
packages/squad-sdk/src/runtime/scheduler.ts
packages/squad-sdk/templates/workflows/squad-ci.yml
packages/squad-sdk/templates/workflows/squad-docs.yml
packages/squad-sdk/templates/workflows/squad-heartbeat.yml
packages/squad-sdk/templates/workflows/squad-insider-release.yml
packages/squad-sdk/templates/workflows/squad-issue-assign.yml
packages/squad-sdk/templates/workflows/squad-label-enforce.yml
packages/squad-sdk/templates/workflows/squad-preview.yml
packages/squad-sdk/templates/workflows/squad-promote.yml
packages/squad-sdk/templates/workflows/squad-release.yml
packages/squad-sdk/templates/workflows/squad-triage.yml
packages/squad-sdk/templates/workflows/sync-squad-labels.yml
.github/workflows/squad-workflow-lint.yml

Reproduction / measurement

Execution-tested command:

git --no-pager grep -n "runs-on: ubuntu-latest\|actions/checkout@\|persist-credentials" -- packages\squad-cli\templates\workflows packages\squad-sdk\templates\workflows packages\squad-cli\src\cli\core\upgrade.ts packages\squad-sdk\src

Relevant output excerpt:

packages/squad-cli/src/cli/core/upgrade.ts:341:      '    runs-on: ubuntu-latest\n' +
packages/squad-cli/src/cli/core/upgrade.ts:343:      '      - uses: actions/checkout@v4\n\n' +
packages/squad-cli/templates/workflows/squad-ci.yml:15:    runs-on: ubuntu-latest
packages/squad-cli/templates/workflows/squad-ci.yml:17:      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 #v4
packages/squad-sdk/src/build/ci-pipeline.ts:118:  lines.push('    runs-on: ubuntu-latest');
packages/squad-sdk/src/build/ci-pipeline.ts:120:  lines.push('      - uses: actions/checkout@v4');
packages/squad-sdk/src/runtime/scheduler.ts:724:        `    runs-on: ubuntu-latest`,
packages/squad-sdk/src/runtime/scheduler.ts:726:        `      - uses: actions/checkout@v4`,

No persist-credentials matches were returned by that command.

Verification bar

The design/implementation should add tests that fail against today’s hardcoded behavior and pass only when:

CLI init and upgrade honor both scalar and array runs-on config values.
Non-npm stubs from generateProjectWorkflowStub honor the same runner and checkout-security policy.
SDK generateGitHubActionsWorkflow can emit the same runner and checkout-security policy as the CLI.
Generated checkout steps include persist-credentials: false by default, unless an explicitly validated policy says otherwise.
Validation rejects control characters and mutable checkout/action references wherever custom refs are accepted.

Traps

This needs a design pass before coding; do not thread one-off parameters through one generator and call it done.
Avoid hardcoding a downstream self-hosted runner label or HealthAgent-specific policy into Squad.
.github/workflows/squad-workflow-lint.yml already exists. Reconcile generated-output validation with it rather than adding a parallel lint path.
Keep this separate from Emitted .lock.yml fails actionlint with 6 errors (copilot-requests scope, concurrency.queue) #1827: gh-aw .lock.yml actionlint schema questions do not define the CLI/SDK runner/checkout configuration model.
If squad upgrade regenerates workflows that fail actionlint/shellcheck (SC2086) and downgrade actions/checkout v7 -> v4 #1556 lands first with a checkout-pin drift guard, this issue should reuse that guard instead of creating a second source of truth.

Out of scope

Fixing squad upgrade overwrites local edits to .github/workflows/* #1493 local-edit preservation.
Fixing gh-aw compiler output or .lock.yml actionlint suppressions from Emitted .lock.yml fails actionlint with 6 errors (copilot-requests scope, concurrency.queue) #1827.
Making changes directly in downstream desharpe/HealthAgent before Squad publishes the generic fix.

Session-stall guard

Before starting: this repo has phantom CRLF diffs (#1793). If git status shows files modified that you did not touch, run git diff --ignore-cr-at-eol. If that output is empty, the diff is line-ending churn, not real edits — run git add --renormalize . and continue. Do not halt and ask for confirmation; halting on phantom diffs is the documented cause of stuck sessions in this repo.

Consolidation note (Ralph triage): Two completed/superseded issues are consolidated here to preserve their unresolved requirements:

squad upgrade regenerates workflows that fail actionlint/shellcheck (SC2086) and downgrade actions/checkout v7 -> v4 #1556 (SC2086/actionlint fixed by PR fix(ci): quote GITHUB_OUTPUT/STEP_SUMMARY redirects (SC2086) + add actionlint/shellcheck gate for workflow templates #1557) — the remaining concern is checkout version preservation: \squad upgrade\ can downgrade \�ctions/checkout\ from v7 to v4 when regenerating workflows. That runner-version-survival requirement carries forward into this umbrella.
Spike: Running Squad's gh-aw workflows on self-hosted / custom runners #1840 (Spike: self-hosted/custom runners) — spike research is complete. Actionable findings: custom runner support requires configurable
uns-on\ per-workflow, and bootstrap dependencies (Node, gh CLI) must be declared or pre-installed. These requirements carry forward here.

Both issues are being closed. This issue (#1502) is the authoritative tracker for runner selection, checkout version pinning, and upgrade-survival behavior.