| name | tsforge-release |
| description | End-to-end tsforge release — validate, commit pending work, bump version, signed tag, push, watch npm publish. Use when the user asks to release, publish, ship, tag, or cut a version. Does not require a clean git tree. Manual-only; do not auto-run during unrelated tasks. |
| disable-model-invocation | true |
tsforge release
One command from dirty main to npm + GitHub Release. Pushing v*.*.* triggers .github/workflows/release.yml.
The script commits everything for you. Uncommitted work is included in the release commit. You do not need a clean tree first.
Run it
./scripts/release.sh --tag-only --yes
./scripts/release.sh patch --yes
./scripts/release.sh minor --yes
./scripts/release.sh major --yes
./scripts/release.sh patch --dry-run
What the script does (in order)
- Requires
main branch
git fetch origin mainbun run validate (unless --skip-validate)- Bumps version in
packages/core, root, and apps/docs package.json (unless --tag-only)
git add -A + signed commit: chore: release X.Y.Z (pending work + version bump together)- Rebases onto
origin/main if behind
- Signed tag
vX.Y.Z
- Pushes
main + tag
- Watches
release.yml via gh run watch
Flags: --dry-run, --no-push, --yes, --tag-only, --skip-validate.
Prerequisites
| Requirement | Check |
|---|
gh authenticated | gh auth status |
| Signed commits/tags | git commit -S and git tag -s must work |
NPM_TOKEN on GitHub | gh secret list | grep NPM_TOKEN |
On main | not a feature branch |
Agent workflow
When the user asks to release, run the script. Do not ask them to commit first.
git branch --show-current (must be main; checkout main if they explicitly want to release from current work)jq -r .version packages/core/package.json- Choose bump: first npm publish →
--tag-only. Otherwise patch / minor / major unless they specify.
- Run
./scripts/release.sh <bump> --yes
- On failure:
gh run view --log-failed on the release workflow
- Report:
bun install -g @agjs/tsforge@VERSION
Do not manually npm publish unless the user explicitly asks to bypass CI.
Version rules
- Tag must match
packages/core/package.json without the v prefix
- Only tag pushes release (not every merge to
main)
--tag-only for first publish when version is already set (e.g. 0.1.0)
Troubleshooting
| Failure | Fix |
|---|
must be on main | git checkout main |
main diverged from origin/main | resolve rebase conflict, re-run |
tag vX.Y.Z already exists | next semver or delete abandoned tag |
| npm publish 401/403 | Regenerate NPM_TOKEN: granular token with Read and write, All packages, Bypass 2FA for automation (or classic Automation token). Verify npm email. gh secret set NPM_TOKEN |
| npm publish 403 name conflict | Unscoped tsforge conflicts with ts-forge on npm — publish as @agjs/tsforge |
| unsigned commit rejected | enable GPG/SSH signing |
Related docs
