Archived

This project has been archived by its maintainers, and is no longer receiving any updates.

uv-release-monorepo

Footgun-free release management for uv workspaces.

Quick Start

uv add --dev uv-release-monorepo
uvr workflow init        # generate .github/workflows/release.yml
uvr release     # detect changes, show plan, dispatch to CI

Releasing

# Preview what would be released
uvr release --dry-run

# Release to CI (default)
uvr release

# Release locally (pure-python packages only)
uvr release --where local

Version bumping

uvr bump --minor             # bump changed packages to next minor
uvr bump --alpha             # enter alpha pre-release cycle
uvr bump --rc                # promote alpha → rc
uvr bump --stable            # exit pre-release → stable
uvr bump --packages my-pkg --patch  # bump specific package(s)

uvr release auto-detects from the version. It strips .devN and publishes whatever is underneath.

uvr release              # 1.0.1.dev0 → release 1.0.1
uvr release              # 1.0.1a0.dev0 → release 1.0.1a0
uvr release --dev        # publish 1.0.1.dev0 as-is

Skipping and reusing

uvr release --skip uvr-build                       # skip the build job
uvr release --skip-to uvr-release                  # skip everything before release
uvr release --skip uvr-build --reuse-run 12345     # reuse artifacts from run 12345

Managing runners

uvr workflow runners                                    # show all package runners
uvr workflow runners my-pkg --add macos-14 windows-latest  # add build runners
uvr workflow runners my-pkg --clear                     # reset to default (ubuntu-latest)

Installing

uvr install --dist dist                    # from local build
uvr install myorg/myrepo/my-pkg            # from GitHub release
uvr install myorg/myrepo/my-pkg@1.2.3      # specific version

Downloading wheels

uvr download myorg/myrepo/my-pkg                  # latest release
uvr download myorg/myrepo/my-pkg -o wheels/       # save to custom dir
uvr download myorg/myrepo/my-pkg --run-id 12345   # from CI artifacts

Hooks

Customize the release pipeline with Python hooks. Subclass ReleaseHook and override the methods you need.

from uv_release_monorepo import ReleaseHook, ReleasePlan

class Hook(ReleaseHook):
    def post_plan(self, plan: ReleasePlan) -> ReleasePlan:
        data = plan.model_dump()
        data["deploy_env"] = "staging"
        return ReleasePlan.model_validate(data)

Configure in pyproject.toml.

[tool.uvr.hooks]
file = "uvr_hooks.py"          # default class: Hook
# or: file = "path/to/file.py:MyHook"

Or just drop a uvr_hooks.py with a Hook class at the workspace root. It's discovered automatically.

Hook points. pre_plan / post_plan (local), pre_build / post_build, pre_build_stage / post_build_stage, pre_build_package / post_build_package, pre_release / post_release, pre_publish / post_publish, pre_bump / post_bump (CI).

How it works

All intelligence lives in uvr release on your machine. The CLI scans your workspace, diffs against baseline tags, walks the dependency graph, pins internal dependencies, expands the build matrix, and assembles a single JSON plan. CI receives the plan and follows it mechanically. No decisions, no debugging.

your machine:  scan → diff → pin → plan → [confirm]
                                              │
CI:                                    validate → build → release → publish → bump

You debug locally with --dry-run. CI stays stable across repo changes. Plans are inspectable JSON. Add your own jobs to the workflow by editing the YAML directly.

Documentation

User Guide. Setup, releasing, hooks, PyPI, skip/reuse, package filtering.
Under the Hood. The plan+execute model, dependency pinning, layered builds, workflow design.

Metadata

Release files for uv-release-monorepo 0.26.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for uv-release-monorepo 0.26.2
File	Interpreter	ABI	Platform	Reset
uv_release_monorepo-0.26.2-py3-none-any.whl 111.0 kB Apr 5, 2026	Python 3	none	any	Details

Release files / uv_release_monorepo-0.26.2-py3-none-any.whl

Download URL	uv_release_monorepo-0.26.2-py3-none-any.whl
Size	111.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`2f05c1ac68f17036772cf8b2eb04b4f842b66f0623b831eb8606af8ddd0a7bac`
BLAKE2b-256 checksum How to use checksums	`f496045057aa867f487cab46b37a1247c9d1c180364141235805a4a779986447`
Upload date	Apr 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.11.3 {"installer":{"name":"uv","version":"0.11.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`