Release Process

Release Process

This is the canonical Squad release runbook. Squad has three release channels and two long-lived branches:

The repository does not use a staging preview branch. Preview is a release channel, not a branch.

Non-negotiable rules

1. Never create release tags or GitHub Releases manually. squad-release.yml creates both.
2. Never reuse a version. A preview such as 0.14.0-preview.1 and stable 0.14.0 are separate immutable releases.
3. Keep the root, SDK, and CLI versions identical.
4. Set the CLI's SDK dependency floor to >=VERSION; prerelease workspaces do not match an older stable range.
5. Add an exact ## [VERSION] entry to CHANGELOG.md.
6. Merge release preparation to dev and wait for CI before dispatching.
7. Keep separate Homebrew casks and WinGet identifiers for each channel.

Required credentials

Configure these GitHub Actions secrets:

• NPM_TOKEN: an automation-capable npm publish token that does not require an interactive OTP.
• HOMEBREW_TAP_TOKEN: a classic GitHub PAT with public_repo, owned by an account that has write access to bradygaster/homebrew-squad.
• WINGET_CREATE_GITHUB_TOKEN: a classic GitHub PAT with public_repo, owned by the account that maintains tamirdresher/winget-pkgs.

Human release-trigger boundary

Agents may prepare versions, run validation, and recommend exact commands, but agents must never execute or dispatch live publication, promotion, or recovery workflows. Only a human executes the real trigger for these live workflows: squad-release.yml, squad-agents-ai-release.yml, squad-insider-publish.yml, squad-promote.yml with dry_run=false, squad-version-promote.yml, squad-npm-publish.yml, or squad-standalone-release.yml. Treat squad-promote.yml --ref dev -f dry_run=true as human-only too: the workflow still has actions: write and contents: write, checks out dev with the workflow token, installs dependencies, and runs the release build and tests. Do not describe any GitHub Actions release workflow as agent-safe once it has write-capable credentials or a dispatch path. Stop with verified commands and evidence for a human to run; human approval alone does not authorize an agent to fire the trigger.

Prepare a release

Verify dev and main share ancestry before changing versions:

git fetch origin dev main
git merge-base origin/dev origin/main

If that command returns no commit, stop and repair ancestry in a separate PR.

Choose a unique SemVer version and update all package manifests:

VERSION=0.14.0-preview.1
npm version "$VERSION" --workspaces --include-workspace-root --no-git-tag-version
npm pkg set "dependencies.@bradygaster/squad-sdk=>=$VERSION" \
  --workspace @bradygaster/squad-cli
npm install --package-lock-only

This updates the root package, both workspaces, and the lockfile. Confirm:

node -p "require('semver').valid('$VERSION')"
grep '"version"' package.json packages/squad-sdk/package.json packages/squad-cli/package.json
grep -F "## [$VERSION]" CHANGELOG.md
SKIP_BUILD_BUMP=1 npm run build
npx vitest run

The validation build must not mutate package versions or the lockfile; check git diff -- package.json packages/squad-sdk/package.json packages/squad-cli/package.json package-lock.json afterward and stop if any version-only change appears.

Release preparation lands through a normal PR to dev. Do not push directly to main.

Publish a preview release

Preview versions must contain a prerelease suffix, for example 0.14.0-preview.1.

After the release-preparation PR is merged and dev CI is green:

Human-only reference command: this live publish workflow must be run by a human. Agents must stop, hand off, and not execute it directly.

VERSION=0.14.0-preview.1
gh workflow run squad-release.yml \
  --ref dev \
  -f confirm_tag="v$VERSION"
gh run watch

The workflow:

1. Requires the dispatch ref to be dev.
2. Rejects a stable X.Y.Z version.
3. Creates v$VERSION and a GitHub prerelease.
4. Publishes both npm packages with --tag preview.
5. Uploads six standalone archives and SHA256SUMS.txt.
6. Updates the squad-preview Homebrew cask and bradygaster.Squad.Preview WinGet package.

Install the resulting preview:

npm install -g @bradygaster/squad-cli@preview

The same preview is available through brew install --cask squad-preview and winget install --id bradygaster.Squad.Preview --exact.

Publish an insider release

Start an on-demand snapshot from dev:

Human-only reference command: this live publish workflow must be run by a human. Agents must stop, hand off, and not execute it directly.

gh workflow run squad-insider-publish.yml --ref dev -f dry_run=false
gh run watch

The workflow computes the next immutable X.Y.Z-insider.N version, publishes npm insider, creates a GitHub prerelease, uploads standalone bundles, updates the squad-insider Homebrew cask, and opens or reuses the bradygaster.Squad.Insider WinGet PR.