cargo-governor

Machine-First, LLM-Ready, CI/CD-Native release automation tool for Rust Cargo workspaces.

Overview

cargo-governor is a command-line tool that automates the release process for Rust projects. It provides two main commands:

• owners — Declarative crate ownership management
• release — Automated version bumping, changelog generation, and publishing

Features

Owners

• Declarative Configuration: Define owners in Cargo.toml metadata
• Group Management: Create logical owner groups reusable across packages
• Workspace Inheritance: Default owners with package-level overrides
• Sync & Validate: Synchronize with crates.io and check for drift

Release

• Semantic Versioning: Automatic version bump detection from conventional commits
• Changelog Generation: Automatic changelog updates with commit categorization
• Workspace Support: Multi-crate workspaces with dependency ordering
• CI/CD Native: JSON output, exit codes, GitHub Actions integration
• Dry Run Mode: Preview changes without executing

Installation

cargo install cargo-governor

Then authenticate with crates.io once:

cargo login

The token is stored in ~/.cargo/credentials.toml and used automatically by cargo-governor.

Commands

Owners Commands

# Show computed owner list
cargo-governor owners show

# Sync with crates.io
cargo-governor owners sync

# Check for drift
cargo-governor owners check

# Dry run
cargo-governor owners sync --dry-run

Release Commands

# Normal UX:
# 1. Make changes
# 2. Commit them with Conventional Commits
# 3. Preview the full workflow
cargo-governor --dry-run release full --format json

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

# Advanced / recovery commands
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

Mutating release commands refuse dirty working trees by default, and they also block manifest versions that drift away from the last release tag. This keeps the default workflow simple: commit first, then let cargo-governor own the release commit/tag/changelog work.

CHANGELOG.md entries are generated from Conventional Commit messages since the last release tag, using the same commit range as semantic version analysis.

Configuration

Add to your Cargo.toml:

Workspace-level 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-level configuration

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

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

JSON Output

For CI/CD integration, use JSON output:

cargo-governor release analyze --format json

Response format:

{
  "success": true,
  "command": "analyze",
  "result": {
    "current_version": "0.1.6",
    "recommended_bump": "minor",
    "new_version": "0.2.0",
    "confidence": 0.95,
    "breaking_changes": [],
    "features": [
      {
        "commit_hash": "abc123",
        "message": "feat: add new feature"
      }
    ]
  }
}

Conventional Commits

Version bump detection follows conventional commits:

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

Examples:

feat(api): add new endpoint
fix: resolve memory leak
feat!: redesign API (breaking)

CI/CD Integration

GitHub Actions

- name: Release
  run: cargo-governor release publish

Note: No CARGO_REGISTRY_TOKEN needed — cargo publish uses the token from cargo login.

Auto-detection

cargo-governor automatically detects CI environments:

• Non-interactive mode (no prompts)
• JSON output by default
• Meaningful exit codes

Exit Codes

License

MIT OR Apache-2.0