governor-application 2.0.0

Application use cases and machine contracts for cargo-governor
Documentation

rust-cargo-governor

unsafe forbidden license

Governance and release automation tooling for Rust Cargo workspaces.

Version 2.0.0 introduces a versioned machine contract for CLI output, an application-layer API, and agent-facing documentation and MCP support.

Overview

cargo-governor provides governance and release automation for Rust projects:

  • owners — Declarative crate ownership management through Cargo.toml
  • release — Automated versioning, changelog generation, and publishing

Define ownership, release policies, and quality gates as code directly in your Cargo.toml files. All policies are version-controlled, reviewed through code review, and enforced in CI.

Installation

cargo install cargo-governor

Then authenticate with crates.io once:

cargo login

Usage

Owners

Manage crate ownership declaratively:

# Show computed owner list
cargo-governor owners show

# Sync with crates.io
cargo-governor owners sync

# Check for drift
cargo-governor owners check

Release

Normal release UX:

# 1. Make changes
# 2. Commit them with Conventional Commits
git commit -m "feat: add release guardrails"

# 3. Preview the full release
cargo-governor --dry-run release full --format json

# 4. Let cargo-governor do the rest
cargo-governor release full --format json

Advanced commands remain available for inspection or recovery:

cargo-governor release status --format json
cargo-governor release analyze --format json
cargo-governor release plan --format json
cargo-governor release bump --format json
cargo-governor release publish --format json

cargo-governor now refuses the confusing workflow where versions are pre-bumped in manifests before release, and mutating release commands also require a clean working tree by default.

CHANGELOG.md is generated from Conventional Commit messages since the last release tag, so release notes follow the same commit range and semantic analysis as the version bump itself.

Coding Agents

cargo-governor now ships a machine-readable agent contract and MCP adapter:

# Load agent context
cargo-governor agent context --format json

# Generate repo-local agent docs and schemas
cargo-governor agent export-docs --output-dir .

# Serve read-only and dry-run tools over MCP stdio
cargo-governor mcp serve

Recommended agent flow:

cargo-governor agent context --format json
cargo-governor release status --format json
cargo-governor release analyze --format json
cargo-governor --dry-run release plan --format json
cargo-governor --dry-run release full --format json

Configuration

Workspace defaults

[workspace.metadata.governor.owners]
default_users = ["org-bot"]

[workspace.metadata.governor.owners.groups]
core = ["alice", "github:myorg:core-team"]
maintainers = ["bob", "carol", "github:myorg:maintainers"]

Package configuration

[package.metadata.governor.owners]
users = ["alice", "bob"]
teams = ["github:myorg:core-team"]

[package.metadata.governor.owners.groups]
inherit = ["core", "maintainers"]

Conventional Commits

Version bump detection follows conventional commits:

  • feat: → minor bump
  • fix: → patch bump
  • feat!: or BREAKING CHANGE: → major bump

CI/CD Integration

- name: Release
  run: cargo-governor --dry-run release plan --format json

For mutating CI release jobs, gate release bump, release publish, and release full behind explicit approval.

No token needed — uses credentials from cargo login.

Development

just build    # Build project
just test     # Run tests
just check    # Format + lint
just fix      # Auto-fix issues
just audit    # Security audit

Project Structure

crates/
├── cargo-governor/       # CLI, presenters, MCP transport, composition root
├── governor-application/ # Use cases and machine contracts
├── governor-cargo/       # Cargo metadata, command, changelog adapters
├── governor-core/        # Domain model and port interfaces
├── governor-cratesio/    # crates.io registry adapter
├── governor-git/         # Git adapter
├── governor-checkpoint/  # Checkpoint/resume adapter
└── governor-owners/      # Owners domain and policies

License

MIT OR Apache-2.0

Repository