Release Workflow

Use this page when preparing a release branch or reviewing the release notes that will become CHANGELOG.md.

What This Covers

The repo uses changelogen from UnJS as the release-note generator. It reads Conventional Commits from git history, groups changes by type, and can update CHANGELOG.md and the root package.json version.

Runtime service logging is separate. Do not replace API, Mastra, Payload, or app runtime logs with consola as part of release-note work; those surfaces keep their existing structured/runtime logger ownership.

Commands

Preview the generated notes without writing files:

bun run release:changelog:preview -- --from <last-release-tag-or-base> --to HEAD

Update CHANGELOG.md only:

bun run release:changelog:update -- --from <last-release-tag-or-base> --to HEAD

Update CHANGELOG.md and bump the root package.json version based on commit types:

bun run release:changelog:bump -- --from <last-release-tag-or-base> --to HEAD

First Release

The repo may not always have a prior release tag. When there is no tag, pass --from explicitly so Changelogen does not scan the full repository history by accident.

Use the last accepted release base, deployment branch point, or commit SHA chosen by the release owner. After the first release tag exists, Changelogen can use its default latest-tag behavior.

Release Checklist

Start from a release branch based on the intended integration branch.
Run git status --short and account for all local changes before generating release notes.
Run the preview command with the correct --from and --to refs.
Run the update or bump command.
Review CHANGELOG.md, package.json, and bun.lock.
Review the latest Chat Orchestration Evals GitHub runs. Chat-related PRs and dev pushes run this workflow automatically, weekday scheduled failures create or update a GitHub issue, and release-candidate refs should be checked with manual workflow dispatch until production release automation owns this gate.
Run the relevant release verification from Verification + Evals.
Commit the generated release artifacts with a Conventional Commit, usually chore(release): v<version>.
Create tags or GitHub releases only through the human-owned release process.

Current Release Automation Boundary

The root bun run release command is an app-owned release-task runner, not a complete production deployment pipeline. It currently delegates to auth release tasks such as configured SSO provider reconciliation.

Production release automation is expected to change. When that workflow is defined, it must enforce the chat orchestration release gate directly instead of relying on this changelog workflow page.

GitHub Releases

Changelogen supports changelogen gh release for creating or updating GitHub releases from CHANGELOG.md. Treat that as an explicit release-owner action, not the default local developer workflow.

Before using it, confirm the repository config and token source. Changelogen supports CHANGELOGEN_TOKENS_GITHUB, GITHUB_TOKEN, GH_TOKEN, a --token CLI argument, global config, or GitHub CLI auth.

Canonical Sources

package.json
changelog.config.json
bun.lock
.agents/rules/commit-messages.md
apps/support-dev/src/content/docs/workflows/verification.md