monorel.disaresta.com

module

v1.0.0 Latest Latest Go to latest Published: May 4, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/disaresta-org/monorel

Links

Open Source Insights

README ¶

monorel

A changesets-style release tool for multi-module Go monorepos. Single-module repos work too (config is just one [packages] entry).

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	Notes
GitHub	`examples/github/`	Composite action wrapper, single workflow file.
Gitea / Forgejo	`examples/gitea/`	Same wrapper on Gitea Actions; `provider.host` set; covers Forgejo via API compatibility.
GitLab	`examples/gitlab/`	Single `.gitlab-ci.yml` using `ghcr.io/disaresta-org/monorel`.

The GitHub flow looks like this:

- uses: actions/checkout@v4
  with: { fetch-depth: 0 }
- uses: actions/setup-go@v5
  with:
    go-version-file: go.mod
- uses: disaresta-org/monorel/ci/github@v1.0.0

The single step runs monorel auto, which detects whether HEAD is the merge of monorel's release PR and dispatches to either the release-cut path (tag + push --follow-tags + publish) or the feature path (apply + push -f + preview --upsert). actions/setup-go is required because monorel's apply step runs go mod tidy against a seeded local cache so the release commit's go.sum is canonically clean. See the GitHub integration page for the full workflow.

If your repo enforces required status checks on the default branch, the bot-created release PR's checks won't fire on the auto-injected token (anti-recursion). Switch to a PAT or GitHub App token. See Tokens and required status checks.

Full setup per provider in the integration guides linked above.

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.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
changelog Package changelog renders a release entry into a per-package CHANGELOG.md file in Keep-a-Changelog format.	Package changelog renders a release entry into a per-package CHANGELOG.md file in Keep-a-Changelog format.
changeset Package changeset reads and writes the .changeset/<name>.md files that drive monorel releases.	Package changeset reads and writes the .changeset/<name>.md files that drive monorel releases.
cmd
monorel command Command monorel is a changesets-style release tool for multi-module Go monorepos.	Command monorel is a changesets-style release tool for multi-module Go monorepos.
config Package config loads and validates monorel.toml.	Package config loads and validates monorel.toml.
doctor Package doctor diagnoses repository state issues that monorel's release planner won't catch on its own.	Package doctor diagnoses repository state issues that monorel's release planner won't catch on its own.
internal
cli Package cli wires the monorel CLI commands.	Package cli wires the monorel CLI commands.
detect Package detect answers a single question: is HEAD the merge commit of monorel's always-open release PR? It checks two signals and returns the first match.	Package detect answers a single question: is HEAD the merge commit of monorel's always-open release PR? It checks two signals and returns the first match.
git Package git is the I/O seam between monorel's planning logic and an underlying git repository.	Package git is the I/O seam between monorel's planning logic and an underlying git repository.
git/testutil Package testutil creates real on-disk git repositories for integration tests of monorel's higher layers.	Package testutil creates real on-disk git repositories for integration tests of monorel's higher layers.
orchestrator Package orchestrator drives the always-open release-PR pattern.	Package orchestrator drives the always-open release-PR pattern.
provider Package provider is the version-control-host seam for monorel.	Package provider is the version-control-host seam for monorel.
provider/bitbucket Package bitbucket is the provider.Client implementation for Bitbucket Cloud (bitbucket.org).	Package bitbucket is the provider.Client implementation for Bitbucket Cloud (bitbucket.org).
provider/factory Package factory constructs a provider.Client from config.ProviderConfig.	Package factory constructs a provider.Client from config.ProviderConfig.
provider/gitea Package gitea is the provider.Client implementation for Gitea and Forgejo (a Gitea fork that maintains API compatibility).	Package gitea is the provider.Client implementation for Gitea and Forgejo (a Gitea fork that maintains API compatibility).
provider/github Package github is the provider.Client implementation for GitHub.com and GitHub Enterprise (via the Host option).	Package github is the provider.Client implementation for GitHub.com and GitHub Enterprise (via the Host option).
provider/gitlab Package gitlab is the provider.Client implementation for GitLab.com and self-hosted GitLab (Community / Enterprise Edition).	Package gitlab is the provider.Client implementation for GitLab.com and self-hosted GitLab (Community / Enterprise Edition).
release Package release applies a plan.ReleasePlan to a working tree.	Package release applies a plan.ReleasePlan to a working tree.
plan Package plan computes a ReleasePlan from the static inputs that drive a monorel release: the parsed monorel.toml, the set of pending changesets, and the list of existing git tags.	Package plan computes a ReleasePlan from the static inputs that drive a monorel release: the parsed monorel.toml, the set of pending changesets, and the list of existing git tags.
semver Package semver wraps github.com/Masterminds/semver/v3 with the bump-level abstraction monorel uses everywhere it touches versions.	Package semver wraps github.com/Masterminds/semver/v3 with the bump-level abstraction monorel uses everywhere it touches versions.
validate Package validate runs a fixed set of static checks against a monorel.toml + the surrounding repo state and reports findings.	Package validate runs a fixed set of static checks against a monorel.toml + the surrounding repo state and reports findings.