toolhive-release

ToolHive Release

Automates the ToolHive release process by analyzing changes and triggering the release PR workflow.

When to Use

• When cutting a new ToolHive release
• When checking what's changed since the last release
• When deciding between patch, minor, or major version bump
• When the user says "release", "cut a release", "new version", or "version bump"

Instructions

Step 1: Find the Last Release

git tag --sort=-v:refname | head -1

This returns the most recent version tag (e.g., v0.8.3).

Step 2: List Commits Since Last Release

git log <last-tag>..HEAD --oneline --no-merges

Count the commits:

git log <last-tag>..HEAD --oneline --no-merges | wc -l

Step 3: Categorize Changes

Analyze each commit and categorize into:

| Category | Description | Version Impact | |----------|-------------|----------------| | New Features | New functionality, new commands, new APIs | Minor bump | | Bug Fixes | Fixes to existing functionality | Patch bump | | Breaking Changes | API changes, removed features, incompatible changes | Major bump | | Improvements | Enhancements to existing features, refactoring | Patch or Minor | | Tests/CI | Test additions, CI/CD changes | No impact | | Documentation | Doc updates, README changes | No impact | | Dependencies | Dependency updates (Renovate PRs) | Patch bump |

Step 4: Recommend Version Bump

Based on the categorization:

• Major (X.0.0): Any breaking changes present
• Minor (0.X.0): New features without breaking changes
• Patch (0.0.X): Only bug fixes, dependency updates, improvements

Present the recommendation with justification to the user.

Step 5: Trigger the Release Workflow

IMPORTANT: Present the analysis and recommendation to the user and WAIT for explicit confirmation before proceeding.

After user confirms the bump type, use the GitHub MCP tool to trigger the workflow:

mcp__github__run_workflow(
  owner: "stacklok",
  repo: "toolhive",
  workflow_id: "create-release-pr.yml",
  ref: "main",
  inputs: { "bump_type": "<patch|minor|major>" }
)

Step 6: Monitor and Report

1. Get the workflow run status:

mcp__github__list_workflow_runs(
  owner: "stacklok",
  repo: "toolhive",
  workflow_id: "create-release-pr.yml",
  per_page: 1
)

1. Poll until completion (check the status field until it shows "completed"):

mcp__github__get_workflow_run(
  owner: "stacklok",
  repo: "toolhive",
  run_id: <run_id from step 1>
)

1. Find the created PR:

mcp__github__list_pull_requests(
  owner: "stacklok",
  repo: "toolhive",
  state: "open",
  sort: "created",
  direction: "desc",
  per_page: 5
)

Look for the PR with title matching "Release v<new-version>".

Report the PR URL to the user.

Release Workflow Chain

For reference, here's what happens after the PR is merged:

1. create-release-pr.yml (manual) → Creates PR with version bumps
2. create-release-tag.yml (auto on VERSION change) → Creates git tag + GitHub Release
3. releaser.yml (auto on release publish) → Builds binaries, images, Helm charts

See [WORKFLOW-REFERENCE.md](references/WORKFLOW-REFERENCE.md) for detailed workflow documentation.

Example Output

## Commits since v0.8.3 (24 commits)

### New Features
- OAuth Authorization Server (#3531, #3513, #3520, #3488)
- ExcludeAll for VirtualMCPServer (#3499)
- Generic PrefixHandlers (#3524)

### Bug Fixes
- OAuth token refresh context cancellation (#3539)
- Custom YAML unmarshalers for registry metadata (#3545)

### Improvements
- Logging updates (#3546, #3547)

### Tests/CI/Docs
- E2E tests for secrets management (#3485)
- Dependency updates

**Recommendation: Minor release (0.9.0)**
New features (OAuth auth server, ExcludeAll) warrant a minor version bump.

Error Handling

• No tags found: Repository may not have any releases yet. Check git tag output.
• Workflow trigger fails: Ensure GitHub MCP server is configured and has proper permissions. The token needs actions:write scope.
• PR not found: The workflow may still be running. Poll mcp__github__get_workflow_run until status is "completed", then search for the PR.
• Workflow run failed: Use mcp__github__get_workflow_run to check the conclusion field. If "failure", use mcp__github__get_job_logs to investigate.