Publishing a release

Project (non-normative maintainer notes) · For: maintainers shipping Cotal

Cotal uses Changesets to version and publish the workspace packages under packages/*, extensions/*, and implementations/* to npm. examples/** is ignored, since it is not published.

0.11 runtime migration

The published binary no longer bundles the optional tmux and cmux runtimes. Existing operators must run cotal ext add @cotal-ai/tmux or cotal ext add @cotal-ai/cmux once after upgrading, before using runtime: tmux|cmux in a manifest or passing --runtime tmux|cmux. Missing runtimes fail loudly with the matching install command; they never fall back to pty.

Trusted publishing

Trusted publishing replaces the long-lived NPM_TOKEN secret with short-lived OIDC tokens issued by GitHub Actions. Each published package must be configured once on npmjs.com.

The fixed group in .changeset/config.json is the list that gets versioned and published. Derive the package list from it instead of maintaining it by hand. It had drifted by six packages before this was last reconciled.

For every published package, cotal-ai (the binary), @cotal-ai/core, @cotal-ai/workspace, @cotal-ai/cli, @cotal-ai/manager, @cotal-ai/delivery, @cotal-ai/web, @cotal-ai/cmux, @cotal-ai/orca, @cotal-ai/tmux, @cotal-ai/herdr, @cotal-ai/connector-core, @cotal-ai/connector-claude-code, @cotal-ai/connector-hermes, @cotal-ai/connector-opencode, @cotal-ai/connector-codex, @cotal-ai/pi, @cotal-ai/auth:

1. Go to https://www.npmjs.com/package/<name>/access (e.g. https://www.npmjs.com/package/@cotal-ai/core/access).
2. Scroll to Trusted publishing → Add a trusted publisher.
3. Pick GitHub Actions.
4. Fill in:
   • Organization or user: the GitHub owner (your org or user).
   • Repository: Cotal.
   • Workflow filename: changesets.yml.
   • Environment name: leave blank.
5. Save. Repeat for every package.

The first time, you may need to publish a version manually (with a classic token) so the package exists on npm. After that, OIDC takes over.

Day-to-day flow

1. Open a PR that changes code in a publishable package.

2. Add a changeset describing the change:

   pnpm changeset

   Pick the affected packages plus the semver bump (patch / minor / major), and write a one-line summary. Commit the generated .changeset/<name>.md file alongside your code change.

3. Merge to main.

4. The Changesets workflow runs:

   • If there are pending changesets, it opens (or updates) a PR titled chore(release): version packages that bumps versions and updates CHANGELOG.md files.
   • When that PR is merged, the same workflow detects the bumped versions, runs pnpm build, and pnpm publishes each changed package to npm with provenance.

Manual publish (escape hatch)

If the workflow is broken, you can run the same steps locally with a classic npm token:

pnpm ci:version
pnpm ci:publish

Set NPM_TOKEN in your environment first. Do not commit the token.

Publication workflow

ci:publish in the root package.json is:

pnpm publish -r --provenance --access=public --no-git-checks

• -r: recursively publish all workspace packages.
• --provenance: emit SLSA provenance attestations (a no-op without OIDC, automatic with it).
• --access=public: required for scoped packages on first publish.
• --no-git-checks: skip pnpm’s branch / clean-tree guard, since CI does not need it.