Deployment Guide

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

Release Process

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()"

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

Review & Merge

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

PyPI Publication

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

Commit Types

Type	Effect	Changelog
`feat`	Minor bump	Visible
`fix`	Patch bump	Visible
`perf`	Patch bump	Visible
`refactor`	Patch bump	Hidden
`docs`	No bump	Hidden
`chore`	No bump	Hidden

Configuration Files

Manifest
Config

.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"
}

release-please-config.json

Setting	Value	Purpose
`release-type`	`python`	Semver + pyproject.toml
`separate-pull-requests`	`true`	One PR per package
`include-component-in-tag`	`true`	Tag: `miu-core-v0.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:

GitHub Actions requests OIDC token
Exchanges token with PyPI for temporary credentials
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

Release PR Not Created

Cause: No commits with conventional formatSolution: Ensure commits use feat:, fix:, or perf: prefixes

Wrong Version Bump

Cause: Commit type doesn’t match intentSolution: Use correct type - feat: for minor, fix: for patch, BREAKING CHANGE: for major

PyPI Publish Fails

Cause: Trusted publisher not configured or version already publishedSolution:

Verify trusted publisher in PyPI project settings
Check workflow has id-token: write permission
Verify version isn’t already published

Getting Started

Core Concepts

Guides

Contributing

API Reference

Deployment Guide

Deployment Guide

Release Process

Commit Types

Configuration Files

GitHub Actions Workflows

Release-Please Workflow

Publish Workflow

PyPI Trusted Publishing

Manual Build

Tag Format

Troubleshooting

Version Checklist

​Deployment Guide

​Release Process

​Commit Types

​Configuration Files

​GitHub Actions Workflows

​Release-Please Workflow

​Publish Workflow

​PyPI Trusted Publishing

​Manual Build

​Tag Format

​Troubleshooting

​Version Checklist

Deployment Guide

Release Process

Commit Types

Configuration Files

GitHub Actions Workflows

Release-Please Workflow

Publish Workflow

PyPI Trusted Publishing

Manual Build

Tag Format

Troubleshooting

Version Checklist