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
)

2. 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>
)

3. 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 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.