Skip to main content

​
Deployment Guide

This guide covers deployment of miu-mono packages to PyPI using Release-Please for automated versioning.

​
Release Process

1

Conventional Commits

All commits must follow Conventional Commits format:
# Feature - MINOR bump (0.1.0 → 0.2.0)
git commit -m "feat(agent): add streaming support"

# Bug fix - PATCH bump (0.1.0 → 0.1.1)
git commit -m "fix(tools): resolve validation bug"

# Breaking change - MAJOR bump (0.1.0 → 1.0.0)
git commit -m "feat(api): redesign Provider interface

BREAKING CHANGE: Provider.execute() renamed to Provider.invoke()"
2

Release-Please Creates PR

When commits are pushed to main:
  • GitHub Actions triggers Release-Please
  • Creates separate PR for each package with changes
  • Updates pyproject.toml version and CHANGELOG.md
3

Review & Merge

Review the generated PR, verify version bumps and CHANGELOG accuracy, then merge.
4

PyPI Publication

After merge, GitHub creates a release which triggers automatic PyPI publication via OIDC trusted publishing.

​
Commit Types

TypeEffectChangelog
featMinor bumpVisible
fixPatch bumpVisible
perfPatch bumpVisible
refactorPatch bumpHidden
docsNo bumpHidden
choreNo bumpHidden

​
Configuration Files

.release-please-manifest.jsonTracks current version for each package:
{
  "packages/miu_core": "0.1.0",
  "packages/miu_code": "0.1.0",
  "packages/miu_examples": "0.1.0",
  "packages/miu_studio": "0.1.0",
  "packages/miu_mono": "0.1.0"
}

​
GitHub Actions Workflows

​
Release-Please Workflow

File: .github/workflows/release-please.yml
  • Triggers: Push to main, manual dispatch
  • Jobs: Creates release PRs and GitHub releases
  • Outputs: Per-package release flags and tag names

​
Publish Workflow

File: .github/workflows/release.yml
  • Triggers: GitHub release event
  • Features: Per-package matrix builds, OIDC trusted publishing
  • No tokens needed - uses PyPI trusted publishing

​
PyPI Trusted Publishing

MIU uses OIDC trusted publishing - no API tokens stored in secrets:
  1. GitHub Actions requests OIDC token
  2. Exchanges token with PyPI for temporary credentials
  3. Publishes without storing secrets
All 5 packages are configured with trusted publishers on PyPI.

​
Manual Build

# Build all packages
uv build

# Build specific package
cd packages/miu_core && uv build

# Verify installation
pip install --upgrade miu-code==0.2.0

​
Tag Format

With Release-Please configuration: 
miu-core-v0.2.0       # miu_core package
miu-code-v0.1.5       # miu_code patch
miu-studio-v0.3.0     # miu_studio feature

​
Troubleshooting

Cause: No commits with conventional formatSolution: Ensure commits use feat:, fix:, or perf: prefixes
Cause: Commit type doesn’t match intentSolution: Use correct type - feat: for minor, fix: for patch, BREAKING CHANGE: for major
Cause: Trusted publisher not configured or version already publishedSolution:
  1. Verify trusted publisher in PyPI project settings
  2. Check workflow has id-token: write permission
  3. Verify version isn’t already published

​
Version Checklist