monorel

A changesets-style release tool for single-module and multi-module Go repos.

monorel manages per-package versions, tags, and CHANGELOG entries in a Go monorepo using explicit .changeset/*.md files instead of inferring releases from commit messages. Pair it with CI on your provider (GitHub, Gitea / Forgejo, or GitLab) to drive an always-open release PR whose diff IS the actual file changes the next release will produce.

Why monorel?

The Go ecosystem has a real gap: no battle-tested release tool fits "main module at repo root with bare vX.Y.Z tags + sub-modules with <path>/vX.Y.Z tags" cleanly. Bare vX.Y.Z tags are required for go install against the root module; per-path-prefix tags are required by Go's module-versioning convention for sub-modules.

• release-please parses Conventional Commits from git history. Friction shows up at squash-merges (per-commit footers don't survive) and on newly-registered packages (full-history scans can leak stray Release-As: overrides from unrelated commits unless you remember to set bootstrap-sha).
• Knope makes per-package tag prefixes mandatory, so the root module can't get the bare vX.Y.Z tags go install needs.
• changesets is JS-native and needs a synthetic package.json in every Go module.

See the introduction for the side-by-side comparison table.

Quickstart

In a Go repo with at least one go.mod:

# 1. Install. monorel.disaresta.com is a vanity import path that
#    resolves to github.com/disaresta-org/monorel via Go's go-import
#    meta tag.
go install monorel.disaresta.com/cmd/monorel@latest

# 2. Scaffold monorel.toml + .changeset/ from your repo
monorel init

# 3. Wire up CI: copy the provider-specific workflow file from
#    examples/{github,gitea,gitlab}/ into your repo

# 4. Author a changeset on a feature branch
monorel add
git commit && gh pr create

# 5. Merge the PR. On the next push to the default branch, the CI
#    workflow runs `monorel auto`, which opens (or refreshes) the
#    always-open release PR. Merge that PR when ready to ship.

Reference setups for each provider live in examples/ (GitHub, Gitea / Forgejo, GitLab). Copy the files you need; the Getting Started walkthrough explains the full lifecycle.

Documentation

• Introduction: why monorel + comparison vs release-please / changesets / Knope.
• Getting Started: install, init, wire up CI, ship the first release.
• Workflows: ASCII diagrams of the daily flow, release cuts, pre-release cycles.
• Cheat Sheet: at-a-glance command map, common one-liners, files monorel reads and writes.
• Configuration: monorel.toml reference.
• CLI: every command and flag.
• Changesets: file format and authoring conventions.
• Integration guides: GitHub, Gitea / Forgejo, GitLab.
• FAQ: the questions that come up after the first release.
• Use with AI / LLMs: paste-ready llms.txt and llms-full.txt for coding assistants.
• Glossary: canonical definitions of monorel terminology.
• Library API: Go packages exposed for programmatic use.

CI integration

monorel ships a composite GitHub Action wrapper plus first-class support for Gitea / Forgejo and GitLab CI. Each provider has a working reference setup under examples/:

Provider	Example	Guide	Notes
GitHub	examples/github/	GitHub integration	Composite action wrapper, single workflow file.
Gitea / Forgejo	examples/gitea/	Gitea / Forgejo integration	Same wrapper on Gitea Actions; provider.host set; covers Forgejo via API compatibility.
GitLab	examples/gitlab/	GitLab integration	Single .gitlab-ci.yml using ghcr.io/disaresta-org/monorel.

Development

git clone https://github.com/disaresta-org/monorel
cd monorel

bun install        # commit-msg linter + docs deps
make hooks         # install git hooks via lefthook
make build         # builds ./monorel
make test-race     # full test suite under -race

See CONTRIBUTING.md for the full dev-loop reference.

License

MIT

---

Made with ❤️ by Theo Gravity / Disaresta.