Automate upstream release docs via Renovate + upstream-release-docs skill

[rdimitrov]

Problem

Today, docs updates for upstream ToolHive releases happen through two uncoordinated channels:

• Reference docs (CLI help, Swagger, CRD schemas) are regenerated automatically by .github/workflows/update-toolhive-reference.yml when stacklok/toolhive publishes a release.
• Content docs (guides, concepts, tutorials) only update when a human notices a release and manually opens a PR. There is no source of truth for "which upstream projects do we document and what version are we pinned at."

This makes content docs reactive, easy to forget, and dependent on a single person tracking upstream changes across multiple repos.

Goal

Make content-doc updates as declarative and tracked as reference updates:

1. A single YAML file lists every upstream project we document with its pinned version.
2. Renovate watches that file and opens a version-bump PR whenever an upstream releases.
3. A reaction workflow augments that PR with source-verified, editorially-polished content edits produced by the upstream-release-docs skill, and requests review from non-bot release contributors.

Tracked projects

id	repo
toolhive	stacklok/toolhive
toolhive-registry-server	stacklok/toolhive-registry-server
toolhive-studio	stacklok/toolhive-studio
toolhive-cloud-ui	stacklok/toolhive-cloud-ui

Approach

• Renovate watches repo: + version: pairs in .github/upstream-projects.yaml via a custom regex manager (github-releases datasource, ignoreUnstable: true, rebaseWhen: never, recreateWhen: never).
• .github/workflows/upstream-release-docs.yml triggers on Renovate-authored pull_request events (with a required label gate) and on workflow_dispatch for manual retry. It runs the upstream-release-docs skill three times (pass 1 + docs-review + re-verification) via anthropics/claude-code-action@v1, pushes content commits to the Renovate branch, augments the PR body in a marker-delimited section, and assigns reviewers extracted from gh api compare.

Acceptance criteria

• PR Automate upstream release docs PRs via Renovate #748 merged
• Renovate's next scan picks up the custom manager (visible on the Mend dashboard)
• First auto-opened Renovate PR triggers the reaction workflow end-to-end
• PR body contains the marker-delimited content summary
• Reviewers are assigned from non-bot release contributors
• docusaurus.config.ts Swagger pin is rewritten by apply-pin-files.mjs
• Workflow failures are flagged with the upstream-docs-failed label and a retry comment
• workflow_dispatch with pr_number idempotently re-runs augmentation
• No collision with update-toolhive-reference.yml when both fire for the same ToolHive release

Follow-ups (out of scope for PR #748)

• Consolidate the upstream-repo list so weekly-product-updates skill and scripts/update-toolhive-reference.sh read from the same YAML.
• Migrate to signed commits if branch protection rejects unsigned github-actions[bot] pushes on Renovate branches (a GitHub App token is the likely fix).
• Add a collaborator filter for the reviewer list if external contributors get surprise notifications.
• Keyword-gate the skill to skip patch-only releases if API spend proves an issue.

Related

• PR: Automate upstream release docs PRs via Renovate #748

[danbarr]

Related: it would be good to triage and close gaps in the existing docs before automating. Note, these were auto-generated, so not everything absolutely needs to be addressed, but there are some high-value gaps noted in each of these:

CLI: #654
Operator: #655
UI: #751

[danbarr]

Also worth noting - today toolhive-cloud-ui has NO representation in the docs. It was considered experimental and thus was kept to in-repo docs only. So the first time this process runs against a cloud-ui release, there will be nothing to compare against.