| name | kitaru-release |
| description | Guide a Kitaru v2 release from branch and changelog review through the current GitHub release workflow, artifact verification, and recovery. Use only for release preparation or execution. |
Kitaru v2 release
The authoritative implementation is .github/workflows/release.yml. Read it before every release because publishing targets, validation gates, inputs, and recovery behavior can change.
This workflow publishes packages and images and advances protected branches. Never dispatch a non-dry-run release or approve a publishing environment without explicit user confirmation.
Release boundary
A normal workflow_dispatch release checks out develop, regardless of the branch from which the workflow is dispatched. A v2 feature or integration branch is not releasable through the normal path until its intended history is present on develop. An existing v<VERSION> tag activates recovery mode and checks out that immutable tag.
If the requested v2 commit is not on the workflow's release source, stop and report the branch mismatch. Do not work around it by pushing directly to develop or main.
1. Refresh and establish the release range
git fetch origin develop main --tags --prune
git status --short
git log -1 --oneline origin/develop
git describe --tags --abbrev=0 origin/main
Use the last immutable release tag as the comparison base. Do not use a potentially force-updated origin/main commit as the release range boundary.
LAST_TAG=$(git describe --tags --abbrev=0 origin/main)
git log "$LAST_TAG"..origin/develop --oneline
git diff "$LAST_TAG"..origin/develop --stat
Stop if the working tree contains changes that are not part of release preparation, another release run is active, or develop does not contain the intended release work.
2. Review version and changelog
Read the current version from pyproject.toml; the workflow updates it during a dispatch release. Review CHANGELOG.md under [Unreleased] against the commits in the release range.
Use semantic versioning:
- patch: compatible fixes and maintenance
- minor: new backward-compatible public capability
- major: intentional breaking public contract
Check every issue or PR reference against the actual release range. Exclude changes that belong only to the sibling marketing repository or that do not affect the released Kitaru package, docs, images, or operational contract.
If the changelog needs editing, make that a focused pull request into the release source branch. Do not silently commit or push release-preparation edits.
3. Select relevant validation
Run the smallest complete set that matches the changed surfaces. The release workflow will rerun its authoritative gates against the release checkout and built artifact.
General source checks
just check
just test
just build
CLI changes
uv sync --frozen --extra cli --extra worker
just test tests/cli
just cli-artifact-smoke
MCP changes
uv sync --frozen --extra mcp
just test tests/mcp
just mcp-schema-check
just build
just mcp-wheel-smoke
Treat any change to the MCP registry, schemas, descriptions, annotations, capability modes, or committed snapshots as public API and security review work. Read the current inventory from tests/mcp/snapshots/metrics.json; do not rely on copied tool counts.
Server, database, task, or worker changes
docker compose up -d db
uv sync --frozen --extra server --extra worker --extra otel
just migration-check
just test tests/server tests/task tests/worker
Docs changes
just docs-build
just docs-validate
The v2 checkout currently lacks scripts/generate_sdk_docs.py, so SDK-reference generation and docs CI are blocked until a reviewed v2 generator lands. Do not use the deleted v1 generator as release evidence.
UI packaging or Docker changes
Read FRONTEND-TESTING.md and docker/CLAUDE.md. Use the current CI and release workflow steps as the validation recipe. Do not use scripts/smoke-test.sh, just ui-smoke, or just release-smoke; the script was removed from v2.
V2 has no tracked tests/live/ provider suite or live_llm marker contract. Do not use inherited v1 adapters, provider-area flags, local ZenML flows, or remote-stack smoke as release evidence.
4. Review the workflow plan
Before dispatch, summarize:
- proposed version and release type
- last release tag and exact
origin/develop SHA
- important user-facing changes
- validation run and results
- any skipped gate and the reason
- whether the stable UI tag should be automatic or explicitly pinned
- whether this is a dry run, normal release, or recovery of an existing tag
Ask for explicit confirmation before any push of release-preparation changes and again before a non-dry-run dispatch.
5. Dispatch
Dry run:
gh workflow run release.yml --ref develop \
-f version=<VERSION> \
-f dry-run=true
Normal release, only after explicit confirmation:
gh workflow run release.yml --ref develop \
-f version=<VERSION> \
-f dry-run=false
Add -f kitaru-ui-tag=<TAG> only when an exact stable UI release was explicitly selected. Otherwise let the workflow resolve its documented stable default.
Capture the run ID immediately and monitor the exact run rather than whichever release run happens to be latest:
gh run list --workflow=release.yml --limit 5
gh run view <RUN_ID>
gh run view <RUN_ID> --log-failed
The workflow validates source, CLI, MCP, migrations, package artifacts, the bundled UI wheel, and installed-wheel contracts before publishing. A real release may pause at its configured GitHub environment approval gate. Leave that approval to the user unless they explicitly ask you to perform it.
6. Verify published state
After success, verify the exact version across the surfaces the workflow publishes:
- Git tag and GitHub Release
- PyPI metadata and attached wheel/sdist assets
- public client and server container tags
- managed image result reported by the workflow
- Helm chart publication
release/<VERSION>, main, and develop state described by the workflow summary- SDK docs deployment when the
main update triggers it
Use the workflow run and attempt as provenance. Do not infer success for one surface from another surface being available.
Recovery
The workflow is designed to recover from an existing matching v<VERSION> tag. A recovery dispatch must reproduce that tagged commit and skips version/changelog/lockfile mutation.
Before retrying:
- Read the failed step and determine which side effects already completed.
- Confirm the existing tag and published artifacts match the workflow's recorded release SHA.
- Fix the workflow on a reviewed branch when the workflow itself is defective; do not advance
develop casually during a partial-release recovery.
- Re-dispatch only after explaining the recovery path and receiving explicit approval.
Never delete or move a published release tag, overwrite a divergent release branch, or retry a partially published version as though no side effects occurred.
