Update ToolHive reference docs for v0.22.0#747
Merged
Conversation
github-actions
Bot
added
the
autogen-docs
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
JAORMX
approved these changes
Apr 21, 2026
rdimitrov
added a commit
that referenced
this pull request
Apr 21, 2026
The unified toolhive path had a broken seam: peter-evans opens PRs with the default GITHUB_TOKEN, and GitHub intentionally does not trigger pull_request workflows on those PRs (recursion guard). Verified on PR #747 - no on-pr.yaml run fired. So the content workflow's pull_request trigger would never fire for toolhive PRs. Fix: add workflow_call trigger to upstream-release-docs.yml and call it as a dependent job from update-toolhive-reference.yml after peter-evans completes. The Renovate path is unaffected - Renovate is a GitHub App identity whose PRs DO trigger workflows. Also: - Distinct concurrency groups per workflow (upstream-release-docs-reference vs -content) so the workflow_call from reference to content doesn't deadlock on a shared group. - Drop the "What will be added next" section from the peter-evans body; the content workflow appends its own section below. - Fix leading-whitespace leak in the bootstrap PR body by using a heredoc + sed strip instead of an inline quoted string. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rdimitrov
added a commit
that referenced
this pull request
Apr 21, 2026
* Automate upstream release docs PRs via Renovate Adds a Renovate custom manager that watches version: pins in .github/upstream-projects.yaml for the four upstream ToolHive projects. When an upstream ships, Renovate opens a version-bump PR; a new workflow reacts to push source-verified content edits produced by the upstream-release-docs skill (three passes with docs-review), assigns reviewers from non-bot release contributors, and augments the PR body in a marker-delimited section. - .github/upstream-projects.yaml: source of truth for tracked projects - renovate.json: customManagers + packageRule (ignoreUnstable, rebaseWhen: never, recreateWhen: never, labels) - .github/workflows/upstream-release-docs.yml: pull_request + dispatch - scripts/upstream-release/detect-change.mjs: finds the changed project and asserts repo: hasn't been tampered with - scripts/upstream-release/apply-pin-files.mjs: rewrites @latest pins - docusaurus.config.ts: pins Registry Server Swagger at v1.2.1 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Add manual bootstrap mode to upstream-release-docs workflow workflow_dispatch now accepts either `pr_number` (retry an existing Renovate PR) or `project_id` + `new_tag` (bootstrap a fresh PR without waiting for Renovate). The bootstrap path branches off main, bumps the YAML via scripts/upstream-release/bump-yaml.mjs, creates the PR with the same labels Renovate applies, and feeds its number into the rest of the workflow so content augmentation runs identically. Useful for debugging, manual updates, and validating the pipeline end-to-end right after merge without waiting for an upstream release. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Unify toolhive reference and content docs into a single PR update-toolhive-reference.yml now also bumps the toolhive entry in .github/upstream-projects.yaml, applies pin_files substitutions, and applies the upstream-content label alongside autogen-docs. The PR it opens is then picked up by upstream-release-docs.yml (via its relaxed gate that accepts github-actions[bot] authors) which adds skill-generated content in a second commit. Renovate is disabled for stacklok/toolhive so it doesn't race the reference workflow. The other three tracked projects keep their Renovate-driven path unchanged. Net: one PR per stacklok/toolhive release instead of two, with the same review surface shape as Renovate-driven PRs for the other projects. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Address Copilot review feedback on PR #748 - Switch upstream-release scripts and the inline node snippet in the workflow from `js-yaml` to the already-declared `yaml` package, so the workflow does not rely on a transitive dependency that could disappear in a future install. Rewrites the `.load()` calls to `.parse()` to match the new package's API. - Filter out null author logins in the `gh api compare` reviewers extraction (`.commits[].author.login? // empty`) so a commit with an unlinked GitHub user cannot pass an empty value into --add-reviewer. - Replace the nested `$([ ... ] && ... || ...)` has_gaps expression with an explicit `if/else` block so the quoting stays obviously correct and resists accidental breakage in future edits. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Chain reference workflow into content via workflow_call The unified toolhive path had a broken seam: peter-evans opens PRs with the default GITHUB_TOKEN, and GitHub intentionally does not trigger pull_request workflows on those PRs (recursion guard). Verified on PR #747 - no on-pr.yaml run fired. So the content workflow's pull_request trigger would never fire for toolhive PRs. Fix: add workflow_call trigger to upstream-release-docs.yml and call it as a dependent job from update-toolhive-reference.yml after peter-evans completes. The Renovate path is unaffected - Renovate is a GitHub App identity whose PRs DO trigger workflows. Also: - Distinct concurrency groups per workflow (upstream-release-docs-reference vs -content) so the workflow_call from reference to content doesn't deadlock on a shared group. - Drop the "What will be added next" section from the peter-evans body; the content workflow appends its own section below. - Fix leading-whitespace leak in the bootstrap PR body by using a heredoc + sed strip instead of an inline quoted string. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Host Registry Server Swagger locally instead of via jsdelivr Per review feedback from Dan: pull the Swagger file from the upstream repo at the pinned tag into static/api-specs/ and reference the local file in docusaurus.config.ts, matching how ToolHive's own Swagger is handled. Keeps the docs build offline-friendly and makes the pin implicit in git history rather than a CDN URL template. - New scripts/upstream-release/sync-assets.mjs helper copies declared files from the shallow clone into the docs repo. No-op when a project declares no assets. - .github/upstream-projects.yaml gains an `assets:` field per project. - Replaced the `pin_files` entry for registry-server with assets. - static/api-specs/toolhive-registry-api.yaml seeded from upstream v1.2.1 (1971 lines). Regenerated automatically on every bump. - Content workflow runs sync-assets right after the shallow clone. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Unify toolhive under the Renovate-driven content pipeline Collapses update-toolhive-reference.yml into upstream-release-docs.yml so all four tracked projects share one trigger path, one workflow, one PR per release. Renovate now watches toolhive's version: the same as the others; the content workflow runs a conditional reference-regen step for toolhive only. Also generalizes the `assets:` schema to support three source types: - source: <path in upstream repo> (file-in-clone copy) - release_asset: <asset name> (gh release download) - release_asset: <asset name>, extract: tar-gz (download + extract) toolhive's swagger and CLI-docs tarball move from the shell script into declarative `assets:` entries. The shell script shrinks to just the CRD MDX generation + toolhive-core schema download (the parts that need custom transforms). It reuses the shallow clone the content workflow already makes. Changes: - Delete .github/workflows/update-toolhive-reference.yml - Remove workflow_call + dual concurrency groups from the content workflow (no chain seam needed without a second workflow) - Remove the Renovate "disable for stacklok/toolhive" packageRule - Extend sync-assets.mjs with release_asset + extract support - Slim update-toolhive-reference.sh; accept TOOLHIVE_CLONE_DIR to reuse the workflow's shallow clone Trade-off: toolhive reference docs now inherit Renovate's 24h minimumReleaseAge. Previously they published within minutes of a release. Acceptable for content coherence; set minimumReleaseAge: 0 per-dep if sub-hour latency becomes needed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Consume toolhive's new release assets, delete the shell script Assumes stacklok/toolhive#4982 has landed. That PR ships three new release assets on toolhive: - thv-crds.tar.gz (the 13 CRD YAMLs) - thv-cli-docs.tar.gz (already existed) - toolhive-*.schema.json (re-exported from toolhive-core at the go.mod-pinned version) And retires the repository_dispatch chain that previously triggered our reference-regen workflow. On our side, the shell wrapper script collapses entirely: - .github/upstream-projects.yaml: toolhive gains five new release_asset entries (swagger, CLI docs tarball with extract, and the four core schemas). sync-assets.mjs handles all of them declaratively. - .github/workflows/upstream-release-docs.yml: the old "run the shell script" step becomes an inline "download + extract CRD tarball, run our three Node helpers" step. Runs only for project_id=toolhive. - A new "Commit regenerated reference assets" step lands the regen as its own commit, so the autogen-detect step below sees only skill- introduced touches (prevents false-positive warnings). - scripts/update-toolhive-reference.sh deleted. Net effect after #4982 merges: - Zero repo clones for CRD processing (tarball replaces clone) - Zero cross-repo downloads (toolhive re-exports core schemas) - Zero shell scripts for release-doc regen - Three Node helpers stay (extract-crd-schemas, generate-crd-pages, bundle-upstream-schema) — they produce docs-specific outputs and genuinely belong on our side. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Refine reference-asset language and attribute gaps to PR authors Two improvements from Dan Barr's review of PR #748: 1. Terminology: "regenerate" was overloaded. It now reads accurately: - "sync" for release-asset downloads / file copies (swagger, CLI tarball, 4 core schemas) — nothing is actually recreated - "regenerate" reserved for the toolhive CRD MDX step which truly transforms upstream manifests into our opinionated layout - "refresh" for the combined commit that may do both The commit that lands reference updates is now titled "Refresh reference assets for <project> <tag>". 2. Gap attribution: the skill's GAPS.md format now includes the PR number and @-mentions the PR author (non-bots only). Previously a gap routed to "everyone in the reviewer pool" via a label; now each gap directly pings the engineer who built the feature. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Derive bootstrap base from dispatching branch, not a new input Simpler than adding a base_ref input: workflow_dispatch always runs against `github.ref_name` (the branch passed to --ref). For production, that's main. For pre-merge testing, dispatch from the feature branch with `gh workflow run --ref feat/branch` and the bootstrap flow branches from, bumps, and opens its PR against that branch. - Bootstrap checkout uses github.ref_name - Bootstrap PR's --base uses github.ref_name - eff step emits base_ref for detect-change.mjs to use as BASE_REF - pull_request trigger: event.pull_request.base.ref - workflow_dispatch retry: gh pr view <n> --json baseRefName - workflow_dispatch bootstrap: github.ref_name Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Drop labels; gate via bot-author + paths filter Labels were doing two jobs — neither worth the friction of pre-creating the labels in every repo that adopts this: 1. Gating which PRs trigger augmentation. Replaced with the existing pull_request paths: filter (only YAML edits) + user.login check (must be renovate[bot]). Human PRs editing the YAML are out of scope; they should be reviewed normally without skill augmentation. 2. Human filtering of "failed" / "needs-context" PRs. Replaced with PR body sections and a failure-path PR comment that carries the run URL. Changes: - Drop labels from Renovate packageRule in renovate.json. - Drop --label from bootstrap gh pr create. - Drop "Add needs-human-context label" step (gaps already shown in PR body). - Simplify failure step to comment-only; drop upstream-docs-failed label. The PR comment already includes the run URL + retry hint. - Drop labeled trigger type; no longer needed without label-race concerns. - Drop label check from workflow_dispatch retry validation. Also unblocks the first real dispatch, which failed on "upstream-content not found" since the label was never pre-created. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Inline node setup after PR-branch checkout The `./.github/actions/setup` composite starts with its own actions/checkout that defaults to the dispatching ref, so calling it after "Checkout PR branch" clobbers the PR-branch working tree with the dispatching branch's content. detect-change.mjs then compared the dispatching branch's YAML against itself and reported "No version changes detected" — blocking the first dispatch. Fix: inline the setup-node + cache + npm ci steps after the PR-branch checkout instead of calling the composite. The composite is still used in the bootstrap flow where re-checkout of the dispatching branch is harmless. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Don't track .claude/scheduled_tasks.lock * Restore id-token: write for claude-code-action OIDC Removed earlier as 'unused'. anthropics/claude-code-action@v1 needs id-token: write to fetch an OIDC token. Skill step was failing with "Could not fetch an OIDC token" on the first real dispatch. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR was auto-generated from ToolHive release v0.22.0. @JAORMX is tagged as the person who cut this release.
What's in this PR
Only machine-generated reference files that are built from the ToolHive source code during the release process:
docs/toolhive/reference/cli/) - help text for everythvcommandstatic/api-specs/toolhive-api.yaml) - OpenAPI/Swagger specdocs/toolhive/reference/crds/,static/api-specs/crds/) - per-CRD MDX pages, extracted JSON schemas, and YAML examplesstatic/api-specs/*.schema.json) - registry validation schemasWhat's NOT in this PR
This PR does not contain guide, tutorial, or conceptual content. Any documentation updates beyond reference files are handled in separate, manually authored PRs.
Review guidance
These files are generated directly from the ToolHive source and are not hand-edited. A quick scan for obvious issues is sufficient - this is intended to be merged shortly after the release is cut so the docs stay in sync.