Automating semantic versioning comes down to letting commit messages decide how big the next release is. Under the Conventional Commits mapping, feat releases a minor, fix a patch, and a commit carrying BREAKING CHANGE: a major. The commit analyzer in semantic-release reads the message itself, not the files the commit touched.
That approach assumes whoever writes the commit understands what each type does to the version. As more commits are written by coding agents, the assumption weakens. An agent may write feat simply because it "added something". In a monorepo, a fix to the docs site written as fix(site) still counts as a package patch. A BREAKING CHANGE: footer added to a refactor ships a major on the next merge. No rule was broken, yet the version is no longer the one the maintainer meant to ship.
The tooling carries a second assumption. A common setup pairs semantic-release for releases with commitlint for commit checks, plus a changelog preset for release notes. Each tool has its own configuration format, so the same type rules live separately in release.config.js, commitlint.config.js, and the preset. Change a rule and you have to confirm it behaves the same in checking, version analysis, and release notes. For an agent, rules spread across config files and plugins also leave no single place to read "what does this type release?"
aronrepo is the tool I built for this: agents and maintainers work from the same rules, and the rules—not the agent's judgment—stop commits that would release by mistake.
One package, one fixed set of rules
aronrepo puts commit checks, version planning, release notes, npm publishing, and GitHub Releases into a single package. There is no separate semantic-release, commitlint, or conventional-changelog to install.
To use it in your own project, visit the aronrepo GitHub repository, copy the installation prompt from the README’s “AI Coding Integration” section, and paste it into your coding agent to have it set up aronrepo for your project.
The design makes a few trade-offs.
Fixed types, one meaning each
Repositories cannot add or rename commit types. Feat is a new capability, Improve a better existing capability, Fix a bug fix in published behavior, Upgrade a change to a runtime dependency, and Chore maintenance; Docs, Test, Build, CI, and similar types do not release. When a type is not on the list or the summary ends with a period, aronrepo check rejects the commit and suggests a valid header. Types and scopes match without case, so fix(core): repair cache is the same commit as Fix(Core): Repair cache, and release notes capitalize each summary; repositories coming from Conventional Commits can keep writing most commits as before.
Fixed types take away per-project customization. I accept that cost: once types are customizable, an agent has to learn each repository's dialect first. With fixed types it only has to decide what kind of change this is, and the rules set the release level.
The owner decides minor and major
In the default explicit mode, every type except Bump(Minor) and Bump(Major) releases at most a patch, and BREAKING CHANGE: footers are rejected. An agent writing Feat ships a patch at most; a minor or major takes an explicit Bump commit. Repositories that want Conventional Commits behavior can switch to auto, where Feat releases a minor and a breaking footer releases a major.
The difference between the modes is what the version number means to the people who use the package.

explicit suits projects that treat minor and major versions as public releases, such as frameworks with published migration guides, design systems, or UI component libraries. In these projects a major usually comes with migration docs, an announcement, and a compatibility window, and a minor may line up with release notes or a docs update; the owner schedules both. Everyday features and fixes keep shipping as patches, and when there is enough to announce, the owner pushes one Bump(Minor). Bump is exempt from the release-path check, so it can be an empty commit, for example git commit --allow-empty -m "Bump(Minor): Release the new theme API". The cost is that new features first appear in patches: users pinning patch updates with a ~ range still receive new APIs, which strict semantic versioning would call a minor.
auto suits projects whose version numbers are read mainly by tools and dependency ranges rather than by people: packages shared inside a team, SDKs consumed by your own applications, or small CLIs and utilities. Users upgrade automatically through ^ ranges and need the version to say precisely whether there is new API or a compatibility break, without anyone scheduling each minor. Here the commit type and BREAKING CHANGE: footer turn straight into the version number, so PR review has to cover commit headers and footers too. aronrepo check --title in CI catches format mistakes; it cannot tell whether a change really breaks compatibility.
Choosing the mode is also the owner's call. aronrepo's rules for agents say so explicitly: when adopting it, an agent must ask the owner which mode to use, and in a repository that already uses it, an agent must not write Bump(Major), Bump(Minor), or a breaking marker unless the user asked for that release in the current conversation.
Commits that touch no published file do not release
aronrepo uses release paths to decide whether a commit touched anything that ships. By default these are the directories of public workspace packages, excluding tests, fixtures, benchmarks, examples, changelogs, and the like. A release-type commit that changes no release path is rejected by aronrepo check before merge and releases nothing. The Fix(Site) from earlier would have to become a non-release type.

Every decision comes with a reason
aronrepo explain lists the next version and why each commit does or does not release. aronrepo release logs the same reasoning when it publishes, and --dry-run prints only the plan and release notes. An agent can run explain before pushing to a release branch, and the maintainer reviewing the PR sees the same conclusion. explain --json also prints the commit that would release (head) and the full release notes, so CI can put them in a job summary and the reviewer approves exactly what will be published.
An interrupted release can be finished
Monorepo releases often fail halfway: some packages are on npm, but the tag was never pushed. aronrepo release first publishes every package on a staging dist-tag, moves the channel's dist-tag only once the registry serves all of them, then pushes the tag and creates the GitHub Release. Rerunning the job skips versions already published from the same commit and fills in a missing tag or release. Versions come only from vX.Y.Z tags; nothing writes the version back into package.json and commits it.
When to release can be the maintainer's call
Releasing on every push is only the default CI setup. Projects with a fixed shipping cadence often want pull requests to keep merging into main and staging to keep deploying, while the production release waits for a maintainer. That needs neither a release branch nor a Release PR: aronrepo counts the version from the last tag to the commit being released, so four Fix commits merged Monday through Thursday still ship as one patch on Friday, with all four in the release notes.
What changes is the trigger. Every push to main runs only explain --json and writes the version, commit, and release notes to the job summary. The release itself becomes a manually triggered workflow that takes the commit and version from that preview and runs in a GitHub Environment with required reviewers, so the approval stays in GitHub's deployment history. The release step runs:
aronrepo release --branch main --expect 1.2.4release first checks that the checked-out commit is actually on origin/main, so a commit from a feature branch never ships as main. --expect recomputes the plan at release time and stops without publishing anything if the version differs from the one that was approved. The next release continues from this tag, and commits merged after the approval wait for the next version. The full workflow is in aronrepo's README.
Give agents data, not documentation
Rules written only in a README still have to be read and remembered. aronrepo exposes one policy through three outlets:
aronrepo policy --jsonprints the repository's mode, release paths, and every type with its release level and description.aronrepo agents --writewrites the policy block intoAGENTS.md, with commands for the repository's package manager. When the block goes stale,aronrepo agentsandaronrepo doctorfail, so nobody copies the type table by hand.aronrepo checkruns the same checks in the commit-msg hook, on every commit of a PR, and on the PR title. When a header fails, it prints a suggested one.
The README also includes a prompt you can paste into a coding agent to adopt aronrepo: inspect the repository, ask the owner which mode to use, remove semantic-release and commitlint, add the hook and CI, then run doctor, explain, and release --dry-run and report the next version. The adoption work itself uses non-release types such as Build, CI, and Chore(Agent).
Compared with semantic-release, release-please, and changesets
JavaScript projects commonly use two other approaches to releases. release-please also reads Conventional Commits, but instead of releasing directly it maintains a Release PR and creates the tag and GitHub Release only when that PR is merged. changesets ignores commit messages entirely: developers attach a changeset file to each change, stating whether it releases a patch, minor, or major.
| Aspect | aronrepo | semantic-release | release-please | changesets |
|---|---|---|---|---|
| Version source | Fixed commit types | Commit messages (Angular convention by default, preset swappable) | Conventional Commits messages | Separately written changeset files |
| Who decides minor and major | explicit: the owner writes Bump; auto: the commit type | Commit type and BREAKING CHANGE | Commit type and !; Release-As can set the version | The level each changeset declares |
| When it releases | On push to a release branch by default, or a maintainer-approved commit on manual trigger | On push to a release branch | When the Release PR is merged | Running changeset version and publish, usually through a Version Packages PR |
| Where the version lives | Only in git tags, never written back to package.json | Git tags; writing back needs @semantic-release/git, which the docs advise against | The Release PR writes package.json and a manifest | changeset version writes package.json |
| Release notes | GitHub Release body | GitHub Release body; CHANGELOG.md needs an extra plugin | CHANGELOG.md and GitHub Release | Per-package CHANGELOG.md |
| Commit checks | Built-in check: hook, every commit in a PR, and the PR title | None; install commitlint separately | None | Ignores commits; changeset status can check for a missing changeset |
| Release-type commit that touches no published file | Rejected before merge, no release | Releases as the message says | Releases for a single package; in a monorepo, changed paths map to packages | Not applicable; the changeset decides |
| Monorepo | Supported, all packages share one version | Core releases one package at a time; monorepos rely on community plugins | Manifest config, independent versions per package, optionally linked | Primary design target, independent versions per package, bindable with fixed and linked |
| Publishing to npm | Built in; publishes to a staging dist-tag and switches once everything is there | Built in (@semantic-release/npm) | Not handled; the workflow needs its own publish step | Built-in changeset publish, publishing only versions not yet on npm |
| Prereleases | alpha, beta, rc, canary branches | Prerelease branches and channels | prerelease setting | pre enter and pre exit mode, plus snapshots |
| Rerun after interruption | Fills in missing publishes, tags, and Releases | Tag is pushed before publishing; a failed publish needs manual repair | Does not publish | Rerunning publish skips published versions |
| Preview before release | explain (--json includes the commit and release notes), release --dry-run | --dry-run | The Release PR itself | changeset status |
| Rules for agents | policy --json, generated AGENTS.md block | None | None | None |
| Scope | JavaScript, npm only | Multiple languages, through plugins | Multiple languages, with a strategy per language | JavaScript package manager workspaces |
When agents write the commits, the four differ in who sets the release level, and when. semantic-release takes it from the commit message and releases on merge. release-please also takes it from the message, but the Release PR gives a person one more look at the version and changelog before release. changesets records the level in the changeset file, so if an agent writes the changeset, the agent picks the level and PR review is the safeguard. aronrepo, in explicit mode, takes minor and major out of the agent's hands and rejects commits that should not release before they merge.
If you need independent versions per package, changesets is the better fit. If you need multiple languages, or want to approve releases by merging a PR inside GitHub's UI, release-please fits better. If you need publish targets beyond npm or specific plugins, semantic-release has the most complete ecosystem.
Install size
Folding the features into one package also shrinks the dependencies. The numbers below come from running npm install --ignore-scripts in a fresh directory for each setup: the package count is npm's reported "added" number, and size is du of node_modules. semantic-release on its own does not check commits; the setup whose scope matches aronrepo is semantic-release plus commitlint. release-please and changesets do not check commits either, so they are measured as their own CLIs.
| Aspect | aronrepo | semantic-release | release-please | changesets |
|---|---|---|---|---|
| Package measured | aronrepo (latest on the day) | semantic-release 25.0.9 | release-please 17.11.2 | @changesets/cli 3.0.3 |
| Node.js requirement | 22.18 or later | ^22.14 or 24.10 or later | 22 or later | ^22.11, ^24, or 26 or later |
| Direct dependencies | 4 | 28 | 31 | 21 |
| Total packages installed | 7 | 301 (345 with commitlint) | 162 | 40 |
node_modules size | 2.7 MB | 79 MB (105 MB with commitlint) | 93 MB | 3.7 MB |
| Main package unpacked size | 366 kB | 128 kB | 929 kB | 89 kB |
Packages installed
aronrepo installs 7 packages, changesets 40, and release-please 162; semantic-release plus commitlint, closest to aronrepo in scope, installs 345.
- aronrepo7
- changesets 3 (@changesets/cli)40
- release-please 17162
- semantic-release 25 (no commit checks)301
- semantic-release 25 + commitlint345
View package count data
| Setup | packages installed |
|---|---|
| aronrepo | 7 |
| changesets 3 (@changesets/cli) | 40 |
| release-please 17 | 162 |
| semantic-release 25 (no commit checks) | 301 |
| semantic-release 25 + commitlint | 345 |
npm install --ignore-scripts in a fresh directory on November 7, 2026, using npm's reported "added" count. The commitlint setup includes @commitlint/cli and @commitlint/config-conventional.
Measurement methodnode_modules size
aronrepo's node_modules is about 2.7 MB and changesets' about 3.7 MB; release-please is about 93 MB, and semantic-release plus commitlint about 105 MB.
- aronrepo2.7
- changesets 3 (@changesets/cli)3.7
- release-please 1793
- semantic-release 25 (no commit checks)79
- semantic-release 25 + commitlint105
View install size data
| Setup | MB (measured with du) |
|---|---|
| aronrepo | 2.7 |
| changesets 3 (@changesets/cli) | 3.7 |
| release-please 17 | 93 |
| semantic-release 25 (no commit checks) | 79 |
| semantic-release 25 + commitlint | 105 |
Same installs as the chart above, measuring node_modules with du; file system block sizes make the values vary slightly.
Measurement methodAgainst semantic-release plus commitlint, the setup with comparable scope, the package count drops from 345 to 7, and the size from about 105 MB to about 2.7 MB. The aronrepo package itself is actually larger than semantic-release (about 366 kB versus 128 kB unpacked), because it bundles commit checks and the CLI; almost the entire gap comes from the dependency tree. aronrepo has only four direct dependencies: semver, js-yaml, picomatch, and tinyglobby.
changesets is similarly light because it neither parses commits nor creates GitHub Releases, leaving that to a separate GitHub Action. release-please's CLI is close to semantic-release in install size, but most projects run it through the official GitHub Action, so it never enters the project's dependencies.
Where it fits, and what it costs
aronrepo's scope is deliberately narrow. It is ESM-only and needs Node.js 22.18 or later; every published package in a repository shares one version; packing uses the repository's package manager, and publishing always goes through npm. Custom commit types, independent versions per package, or registry flows other than npm are outside its design.
Projects that already have their own hardened release pipeline do not have to replace it wholesale. The functions behind the CLI are exported from aronrepo/node, and the commit standard, version, and release-notes helpers from aronrepo. You can let aronrepo decide the version, tag, and notes while your existing scripts keep packing, verifying, and uploading.
I built aronrepo around one shift: moving version decisions from "did whoever wrote the commit judge correctly?" to "can the rules stop it before merge?" Agents will still pick the wrong type. The difference is that when they do, check rejects it with a replacement, and minor and major always need the owner to write them down.
