Update stacklok/toolhive to v0.23.1 #17
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
| name: Upstream Release Docs | |
| # Reacts to Renovate-authored PRs that bump a `version:` in | |
| # .github/upstream-projects.yaml. For all four tracked projects | |
| # (toolhive, toolhive-registry-server, toolhive-studio, | |
| # toolhive-cloud-ui), the flow is identical: | |
| # | |
| # 1. Renovate opens a version-bump PR | |
| # 2. This workflow fires on the PR event, detects which project | |
| # changed, shallow-clones the upstream at the new tag | |
| # 3. Syncs declared upstream assets into static/ via sync-assets.mjs | |
| # (release-asset downloads, tarball extractions, file-from-clone | |
| # copies — see `assets:` in upstream-projects.yaml) | |
| # 4. For toolhive specifically, downloads the CRD manifests tarball | |
| # and runs extract-crd-schemas.mjs + generate-crd-pages.mjs + | |
| # bundle-upstream-schema.mjs to produce our opinionated reference | |
| # MDX (the CRD tarball and toolhive-core schemas are shipped as | |
| # release assets by stacklok/toolhive#4982) | |
| # 5. Runs the upstream-release-docs skill (3 passes) to produce | |
| # source-verified content edits | |
| # 6. Commits everything to the PR branch, augments the PR body, | |
| # assigns reviewers from non-bot release contributors | |
| # | |
| # Renovate is configured with rebaseWhen: never + recreateWhen: never | |
| # so we can push commits without force-push races. | |
| on: | |
| pull_request: | |
| types: [opened, reopened] | |
| paths: | |
| - '.github/upstream-projects.yaml' | |
| workflow_dispatch: | |
| inputs: | |
| pr_number: | |
| description: 'Retry-only: PR number to re-augment (must be an open Renovate PR). Leave blank to bootstrap a new PR via project_id + new_tag.' | |
| required: false | |
| type: string | |
| project_id: | |
| description: 'Bootstrap a new PR: id from .github/upstream-projects.yaml (e.g. toolhive-registry-server). Requires new_tag.' | |
| required: false | |
| type: string | |
| new_tag: | |
| description: 'Bootstrap a new PR: the upstream tag to document (e.g. v1.3.0). Requires project_id.' | |
| required: false | |
| type: string | |
| permissions: | |
| contents: write | |
| pull-requests: write | |
| # Required by anthropics/claude-code-action@v1 for OIDC token exchange. | |
| id-token: write | |
| concurrency: | |
| # Workflow-level group so two simultaneous upstream releases don't | |
| # run the skill in parallel on shared concept pages. | |
| group: upstream-release-docs | |
| cancel-in-progress: false | |
| jobs: | |
| augment: | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 90 | |
| # Gate: two accepted entry points. | |
| # - pull_request: Renovate-authored PR touching upstream-projects.yaml | |
| # (the `paths:` filter on the trigger already narrows to YAML edits). | |
| # - workflow_dispatch: human manually retries or bootstraps. | |
| # Human-authored PRs that happen to edit the YAML are out of scope and | |
| # should be reviewed normally without skill augmentation. | |
| if: | | |
| github.event_name == 'workflow_dispatch' || | |
| ( | |
| github.event_name == 'pull_request' && | |
| github.event.pull_request.user.login == 'renovate[bot]' | |
| ) | |
| env: | |
| GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| steps: | |
| - name: Validate workflow_dispatch inputs | |
| if: github.event_name == 'workflow_dispatch' | |
| env: | |
| PR_NUMBER_IN: ${{ github.event.inputs.pr_number }} | |
| PROJECT_ID_IN: ${{ github.event.inputs.project_id }} | |
| NEW_TAG_IN: ${{ github.event.inputs.new_tag }} | |
| run: | | |
| # Exactly one of: (pr_number) OR (project_id + new_tag). | |
| if [ -n "$PR_NUMBER_IN" ] && { [ -n "$PROJECT_ID_IN" ] || [ -n "$NEW_TAG_IN" ]; }; then | |
| echo "::error::Provide either pr_number (retry) or project_id + new_tag (bootstrap), not both." | |
| exit 1 | |
| fi | |
| if [ -z "$PR_NUMBER_IN" ] && { [ -z "$PROJECT_ID_IN" ] || [ -z "$NEW_TAG_IN" ]; }; then | |
| echo "::error::Bootstrap mode requires both project_id and new_tag." | |
| exit 1 | |
| fi | |
| - name: Resolve PR number and head ref | |
| id: pr | |
| env: | |
| EVENT: ${{ github.event_name }} | |
| DISPATCH_PR: ${{ github.event.inputs.pr_number }} | |
| PROJECT_ID_IN: ${{ github.event.inputs.project_id }} | |
| NEW_TAG_IN: ${{ github.event.inputs.new_tag }} | |
| EVENT_PR: ${{ github.event.pull_request.number }} | |
| EVENT_HEAD_REF: ${{ github.event.pull_request.head.ref }} | |
| run: | | |
| case "$EVENT" in | |
| pull_request) | |
| PR_NUMBER="$EVENT_PR" | |
| HEAD_REF="$EVENT_HEAD_REF" | |
| MODE="react" | |
| ;; | |
| workflow_dispatch) | |
| if [ -n "$DISPATCH_PR" ]; then | |
| PR_NUMBER="$DISPATCH_PR" | |
| # --repo is required because this step runs before the | |
| # actions/checkout below — gh otherwise looks for a | |
| # local .git context and fails with "not a git repository". | |
| HEAD_REF=$(gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json headRefName --jq .headRefName) | |
| AUTHOR=$(gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json author --jq '.author.login') | |
| case "$AUTHOR" in | |
| app/renovate|renovate[bot]|app/github-actions|github-actions[bot]) | |
| ;; | |
| *) | |
| echo "::error::PR #$PR_NUMBER author '$AUTHOR' is not an accepted bot. Retry mode accepts renovate[bot] or github-actions[bot]; use bootstrap (project_id + new_tag) for a fresh manual PR." | |
| exit 1 | |
| ;; | |
| esac | |
| MODE="retry" | |
| else | |
| # Bootstrap: branch and PR are created in the next step. | |
| PR_NUMBER="" | |
| HEAD_REF="" | |
| MODE="bootstrap" | |
| fi | |
| ;; | |
| esac | |
| { | |
| echo "number=$PR_NUMBER" | |
| echo "head_ref=$HEAD_REF" | |
| echo "mode=$MODE" | |
| } >> "$GITHUB_OUTPUT" | |
| echo "Mode: $MODE" | |
| # Bootstrap: a human manually dispatched with project_id + new_tag. | |
| # Check out the dispatching branch (main in production; any branch | |
| # for pre-merge testing — just dispatch via `gh workflow run --ref | |
| # <branch>`), bump the YAML, create the PR, and emit its number + | |
| # branch so the rest of the workflow proceeds as if Renovate had | |
| # opened it. | |
| - name: Checkout dispatching branch for bootstrap | |
| if: steps.pr.outputs.mode == 'bootstrap' | |
| uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 | |
| with: | |
| ref: ${{ github.ref_name }} | |
| fetch-depth: 0 | |
| - name: Setup (bootstrap) | |
| if: steps.pr.outputs.mode == 'bootstrap' | |
| uses: ./.github/actions/setup | |
| - name: Set up Git (bootstrap) | |
| if: steps.pr.outputs.mode == 'bootstrap' | |
| run: | | |
| git config --global user.name "github-actions[bot]" | |
| git config --global user.email "github-actions[bot]@users.noreply.github.com" | |
| - name: Bootstrap branch and PR | |
| id: bootstrap | |
| if: steps.pr.outputs.mode == 'bootstrap' | |
| env: | |
| PROJECT_ID: ${{ github.event.inputs.project_id }} | |
| NEW_TAG: ${{ github.event.inputs.new_tag }} | |
| BASE_REF: ${{ github.ref_name }} | |
| ACTOR: ${{ github.actor }} | |
| RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} | |
| run: | | |
| # Branch name intentionally distinct from Renovate's | |
| # docs/upstream-<id> so the two paths don't collide. | |
| BRANCH="manual/upstream-${PROJECT_ID}-${NEW_TAG}" | |
| if git ls-remote --exit-code --heads origin "$BRANCH" >/dev/null 2>&1; then | |
| echo "::error::Branch $BRANCH already exists on origin. Delete it or use retry mode with the existing PR's number." | |
| exit 1 | |
| fi | |
| git checkout -b "$BRANCH" | |
| node scripts/upstream-release/bump-yaml.mjs \ | |
| --id "$PROJECT_ID" \ | |
| --tag "$NEW_TAG" | |
| git add .github/upstream-projects.yaml | |
| git commit -m "Bump $PROJECT_ID to $NEW_TAG" | |
| git push origin "$BRANCH" | |
| # Heredoc so the YAML indent doesn't leak into the PR body. | |
| cat > /tmp/bootstrap-body.md <<EOF | |
| Manually dispatched by @$ACTOR via workflow run $RUN_URL. | |
| This PR was created by the \`Upstream Release Docs\` workflow's bootstrap mode to document a release without waiting for Renovate. Content edits will be pushed as additional commits by the same workflow run. | |
| EOF | |
| # Strip the leading 10-space indent the heredoc inherits from | |
| # YAML nesting so the body renders cleanly. | |
| sed -i 's/^ //' /tmp/bootstrap-body.md | |
| gh pr create \ | |
| --base "$BASE_REF" \ | |
| --head "$BRANCH" \ | |
| --title "Update $PROJECT_ID to $NEW_TAG (manual dispatch)" \ | |
| --body-file /tmp/bootstrap-body.md | |
| PR_NUMBER=$(gh pr view "$BRANCH" --json number --jq .number) | |
| echo "number=$PR_NUMBER" >> "$GITHUB_OUTPUT" | |
| echo "head_ref=$BRANCH" >> "$GITHUB_OUTPUT" | |
| # Normalize the (possibly bootstrap-created) PR number, head_ref, | |
| # and base_ref into a single step output so later steps reference | |
| # one place. base_ref drives detect-change.mjs (the baseline to | |
| # diff against) and the CRD-regen paths. | |
| - name: Resolve effective PR metadata | |
| id: eff | |
| env: | |
| EVENT: ${{ github.event_name }} | |
| PR_FROM_RESOLVE: ${{ steps.pr.outputs.number }} | |
| HEAD_FROM_RESOLVE: ${{ steps.pr.outputs.head_ref }} | |
| PR_FROM_BOOTSTRAP: ${{ steps.bootstrap.outputs.number }} | |
| HEAD_FROM_BOOTSTRAP: ${{ steps.bootstrap.outputs.head_ref }} | |
| BASE_FROM_EVENT: ${{ github.event.pull_request.base.ref }} | |
| DISPATCH_REF_NAME: ${{ github.ref_name }} | |
| run: | | |
| if [ -n "$PR_FROM_BOOTSTRAP" ]; then | |
| # Bootstrap mode: the PR was just created with --base set to | |
| # the dispatching branch (main in production; feat branch | |
| # when testing pre-merge). | |
| NUMBER="$PR_FROM_BOOTSTRAP" | |
| HEAD="$HEAD_FROM_BOOTSTRAP" | |
| BASE="$DISPATCH_REF_NAME" | |
| elif [ "$EVENT" = "pull_request" ]; then | |
| NUMBER="$PR_FROM_RESOLVE" | |
| HEAD="$HEAD_FROM_RESOLVE" | |
| BASE="$BASE_FROM_EVENT" | |
| else | |
| # workflow_dispatch retry: look up the PR's base_ref. | |
| # --repo because in retry mode there's no prior checkout. | |
| NUMBER="$PR_FROM_RESOLVE" | |
| HEAD="$HEAD_FROM_RESOLVE" | |
| BASE=$(gh pr view "$NUMBER" --repo "$GITHUB_REPOSITORY" --json baseRefName --jq .baseRefName) | |
| fi | |
| { | |
| echo "number=$NUMBER" | |
| echo "head_ref=$HEAD" | |
| echo "base_ref=$BASE" | |
| } >> "$GITHUB_OUTPUT" | |
| - name: Checkout PR branch | |
| uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 | |
| with: | |
| ref: ${{ steps.eff.outputs.head_ref }} | |
| fetch-depth: 0 | |
| # NOTE: we inline the node/deps setup rather than calling the | |
| # ./.github/actions/setup composite because that composite starts | |
| # with its own actions/checkout that overwrites the PR-branch | |
| # checkout above with the dispatching branch. | |
| - name: Set up Node.js | |
| uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6 | |
| with: | |
| node-version: '24.15.0' | |
| - name: Cache dependencies | |
| id: cache | |
| uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5 | |
| with: | |
| path: ./node_modules | |
| key: modules-${{ hashFiles('package-lock.json') }} | |
| - name: Install dependencies | |
| if: steps.cache.outputs.cache-hit != 'true' | |
| run: npm ci | |
| - name: Set up Git | |
| run: | | |
| git config --global user.name "github-actions[bot]" | |
| git config --global user.email "github-actions[bot]@users.noreply.github.com" | |
| - name: Detect changed project | |
| id: detect | |
| env: | |
| # Pass the PR's actual base (main in production; dispatching | |
| # branch when bootstrap was run via gh workflow run --ref). | |
| BASE_REF: origin/${{ steps.eff.outputs.base_ref }} | |
| run: node scripts/upstream-release/detect-change.mjs | |
| - name: Verify prev_tag exists upstream | |
| env: | |
| REPO: ${{ steps.detect.outputs.repo }} | |
| PREV_TAG: ${{ steps.detect.outputs.prev_tag }} | |
| run: | | |
| # Sanity check: if the pinned prev_tag doesn't exist upstream | |
| # (e.g., a fake v0.0.0 seed, a retagged release, a deleted tag), | |
| # fail early rather than let the skill produce a confusing diff. | |
| if ! gh api "repos/$REPO/git/refs/tags/$PREV_TAG" --silent 2>/dev/null; then | |
| echo "::error::prev_tag $PREV_TAG does not exist in $REPO. The pinned version in .github/upstream-projects.yaml may be wrong or the upstream tag was deleted. Fix the pinned version and re-run." | |
| exit 1 | |
| fi | |
| - name: Shallow-clone upstream at new tag | |
| id: clone | |
| env: | |
| REPO: ${{ steps.detect.outputs.repo }} | |
| NEW_TAG: ${{ steps.detect.outputs.new_tag }} | |
| run: | | |
| SCRATCH=$(mktemp -d) | |
| git clone --depth 1 --branch "$NEW_TAG" \ | |
| "https://github.com/${REPO}.git" \ | |
| "$SCRATCH/upstream" | |
| echo "scratch_dir=$SCRATCH/upstream" >> "$GITHUB_OUTPUT" | |
| - name: Sync declared assets | |
| env: | |
| PROJECT_ID: ${{ steps.detect.outputs.id }} | |
| CLONE_DIR: ${{ steps.clone.outputs.scratch_dir }} | |
| REPO: ${{ steps.detect.outputs.repo }} | |
| NEW_TAG: ${{ steps.detect.outputs.new_tag }} | |
| run: | | |
| node scripts/upstream-release/sync-assets.mjs \ | |
| --id "$PROJECT_ID" \ | |
| --clone "$CLONE_DIR" \ | |
| --repo "$REPO" \ | |
| --tag "$NEW_TAG" | |
| # toolhive ships CRD manifests as a release asset tarball (see | |
| # stacklok/toolhive#4982). We extract it to a temp dir and run our | |
| # opinionated transforms: extract per-CRD JSON schemas + examples, | |
| # generate MDX reference pages. Bundling the upstream-registry | |
| # schema (resolves the remote MCP-server $refs for our JSON-Schema | |
| # viewer) also runs here. | |
| - name: Extract CRDs + generate reference MDX (toolhive) | |
| if: steps.detect.outputs.id == 'toolhive' | |
| env: | |
| REPO: ${{ steps.detect.outputs.repo }} | |
| NEW_TAG: ${{ steps.detect.outputs.new_tag }} | |
| run: | | |
| TMP=$(mktemp -d) | |
| gh release download "$NEW_TAG" --repo "$REPO" \ | |
| --pattern "thv-crds.tar.gz" --dir "$TMP" | |
| mkdir -p "$TMP/crds" | |
| tar -xzf "$TMP/thv-crds.tar.gz" -C "$TMP/crds" | |
| TOOLHIVE_CRD_DIR="$TMP/crds" node scripts/extract-crd-schemas.mjs | |
| node scripts/generate-crd-pages.mjs | |
| node scripts/bundle-upstream-schema.mjs | |
| rm -rf "$TMP" | |
| # Commit AND PUSH the refreshed reference assets (synced release- | |
| # asset files + regenerated toolhive CRD MDX if applicable) before | |
| # the skill runs. Pushing here — rather than batching the push | |
| # with the skill-content commit later — means refresh work is | |
| # preserved on the PR even if the skill step fails or is | |
| # cancelled. Also keeps the skill's content commit clean and | |
| # lets the autogen-detect step below distinguish skill touches | |
| # from our own legitimate refresh writes. | |
| - name: Commit + push refreshed reference assets | |
| env: | |
| PROJECT_ID: ${{ steps.detect.outputs.id }} | |
| NEW_TAG: ${{ steps.detect.outputs.new_tag }} | |
| HEAD_REF: ${{ steps.eff.outputs.head_ref }} | |
| run: | | |
| git add -A | |
| if git diff --cached --quiet; then | |
| echo "No reference changes for $PROJECT_ID $NEW_TAG." | |
| else | |
| git commit -m "Refresh reference assets for $PROJECT_ID $NEW_TAG" | |
| # Someone may have pushed to HEAD_REF between our checkout | |
| # and now (merges from main, etc). Rebase onto the latest | |
| # tip before pushing so we don't fail with "fetch first". | |
| git fetch origin "$HEAD_REF" --quiet | |
| git rebase "origin/$HEAD_REF" || { | |
| echo "::error::Rebase of the refresh commit onto origin/$HEAD_REF hit conflicts. Resolve manually on the PR branch." | |
| exit 1 | |
| } | |
| git push origin "HEAD:$HEAD_REF" | |
| fi | |
| - name: Extract reviewers from release compare | |
| id: reviewers | |
| env: | |
| REPO: ${{ steps.detect.outputs.repo }} | |
| PREV: ${{ steps.detect.outputs.prev_tag }} | |
| NEW: ${{ steps.detect.outputs.new_tag }} | |
| REVIEW_REPO: ${{ github.repository }} | |
| run: | | |
| # Get non-bot commit authors in the release range. | |
| if COMPARE=$(gh api "repos/$REPO/compare/$PREV...$NEW" \ | |
| --jq '[.commits[].author.login? // empty] | unique | .[]' 2>/dev/null); then | |
| echo "compare_ok=true" >> "$GITHUB_OUTPUT" | |
| else | |
| COMPARE="" | |
| echo "compare_ok=false" >> "$GITHUB_OUTPUT" | |
| fi | |
| # Filter out bot accounts, then further filter to only this | |
| # repo's collaborators. GitHub rejects reviewer requests for | |
| # non-collaborators with 422, which would fail the whole | |
| # `gh pr edit --add-reviewer` call and drop the valid | |
| # reviewers along with the invalid ones. Community | |
| # contributors from the upstream repo often aren't | |
| # collaborators here; silently skip them. | |
| CANDIDATES=$(echo "$COMPARE" | | |
| grep -Ev '(\[bot\]$|^github-actions|^stacklokbot$|^dependabot|^renovate|^copilot)' || true) | |
| REVIEWERS="" | |
| while IFS= read -r login; do | |
| [ -z "$login" ] && continue | |
| if gh api "repos/$REVIEW_REPO/collaborators/$login" --silent 2>/dev/null; then | |
| REVIEWERS="${REVIEWERS:+$REVIEWERS,}$login" | |
| fi | |
| done <<< "$CANDIDATES" | |
| # Cap at 5 to avoid review fatigue. | |
| REVIEWERS=$(echo "$REVIEWERS" | tr ',' '\n' | head -5 | paste -sd, -) | |
| echo "list=$REVIEWERS" >> "$GITHUB_OUTPUT" | |
| echo "Reviewers: ${REVIEWERS:-<none>}" | |
| - name: Read docs_paths hint | |
| id: hints | |
| env: | |
| PROJECT_ID: ${{ steps.detect.outputs.id }} | |
| run: | | |
| HINTS=$(node -e " | |
| const yaml = require('yaml'); | |
| const fs = require('fs'); | |
| const p = yaml.parse(fs.readFileSync('.github/upstream-projects.yaml','utf8')).projects.find(x=>x.id===process.env.PROJECT_ID); | |
| console.log(JSON.stringify(p?.docs_paths ?? [])); | |
| ") | |
| echo "docs_paths=$HINTS" >> "$GITHUB_OUTPUT" | |
| # Invocation 1: generation. Runs /upstream-release-docs end-to- | |
| # end (all 6 phases, including the skill's own internal | |
| # docs-review in Phase 5). Uses Opus 4.7 — generation benefits | |
| # from the stronger model on long multi-file edits and source | |
| # verification. | |
| - name: Run upstream-release-docs skill (generation) | |
| id: skill_gen | |
| uses: anthropics/claude-code-action@38ec876110f9fbf8b950c79f534430740c3ac009 # v1 | |
| with: | |
| anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} | |
| additional_permissions: | | |
| actions: read | |
| # Allow the action to run when the triggering PR was opened | |
| # by Renovate. Without this, claude-code-action refuses to | |
| # run for bot-initiated workflows as a safety default. | |
| allowed_bots: 'renovate' | |
| # Real-time visibility into skill progress during long runs. | |
| # track_progress posts a sticky tracking comment on the PR | |
| # that updates as the skill works through each phase — | |
| # BUT it's only supported for pull_request / issue_comment | |
| # /* events. Setting it on workflow_dispatch fails the | |
| # action with "track_progress is only supported for events | |
| # ... Current event: workflow_dispatch", so gate it on the | |
| # triggering event. | |
| # display_report surfaces the Claude Code Report in the | |
| # Actions Step Summary regardless of trigger. | |
| track_progress: ${{ github.event_name == 'pull_request' }} | |
| display_report: true | |
| claude_args: | | |
| --model claude-opus-4-7 | |
| prompt: | | |
| You are running in GitHub Actions with no interactive user. Follow | |
| these steps exactly and do NOT ask clarifying questions -- proceed | |
| best-effort at every decision point. | |
| PROJECT: ${{ steps.detect.outputs.id }} | |
| REPO: ${{ steps.detect.outputs.repo }} | |
| PREV_TAG: ${{ steps.detect.outputs.prev_tag }} | |
| NEW_TAG: ${{ steps.detect.outputs.new_tag }} | |
| CLONE: ${{ steps.clone.outputs.scratch_dir }} | |
| DOCS_HINTS: ${{ steps.hints.outputs.docs_paths }} | |
| Run /upstream-release-docs ${{ steps.detect.outputs.repo }} ${{ steps.detect.outputs.new_tag }} | |
| Execute all 6 phases. Prefer reading source code from the | |
| local clone at ${{ steps.clone.outputs.scratch_dir }} | |
| instead of `gh api contents?ref=<tag>` -- it's already at | |
| the tag and doesn't consume API quota. | |
| For Phase 2 step 4 (context on major new features), SKIP | |
| writing the "why"/consumer narrative and append one bullet | |
| per gap to GAPS.md at repo root (create if missing). Each | |
| bullet MUST: | |
| - Name the feature | |
| - Reference the PR that introduced it, using the PR | |
| number you found in Phase 2 deep-dive | |
| - @-mention the PR author by their GitHub handle (skip | |
| this for bot authors like renovate[bot] or | |
| github-actions[bot]) | |
| - Describe what context a human needs to supply | |
| Format: `- Feature X (PR #123 by @alice): needs a user | |
| story explaining who this is for and the expected | |
| consumer workflow.` | |
| This routes gaps to the engineer who built the feature | |
| rather than the whole reviewer pool. | |
| Follow the skill's own guidance on auto-generated reference | |
| files (Phase 4 step 5, Phase 4 step 6) -- do not hand-edit | |
| docs/toolhive/reference/cli/, static/api-specs/, or | |
| docs/toolhive/reference/crds/. Those are synced or | |
| regenerated from release assets by earlier steps in this | |
| workflow; if a release genuinely needs hand-written | |
| reference updates, note that in GAPS.md. | |
| If you conclude there are no doc-relevant changes for this | |
| release (Phase 3 impact map is empty), stop and write | |
| NO_CHANGES.md at repo root with a one-line explanation. | |
| Still do not hand-edit any file. | |
| # Invocation 2: editorial re-review with FRESH CONTEXT. Running | |
| # docs-review in a separate session — with no exposure to the | |
| # generation session's internal reasoning — tends to catch style | |
| # and structure issues the generation pass rationalized away. | |
| # Also uses Opus 4.7 since docs-review benefits from the same | |
| # model quality. | |
| - name: Run docs-review on skill output (fresh context) | |
| id: skill_review | |
| if: always() && steps.skill_gen.conclusion == 'success' | |
| uses: anthropics/claude-code-action@38ec876110f9fbf8b950c79f534430740c3ac009 # v1 | |
| with: | |
| anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} | |
| additional_permissions: | | |
| actions: read | |
| allowed_bots: 'renovate' | |
| track_progress: ${{ github.event_name == 'pull_request' }} | |
| display_report: true | |
| claude_args: | | |
| --model claude-opus-4-7 | |
| prompt: | | |
| You are running in GitHub Actions with no interactive user. Follow | |
| these steps exactly and do NOT ask clarifying questions -- proceed | |
| best-effort at every decision point. | |
| A previous Claude session just generated content for the | |
| upstream release ${{ steps.detect.outputs.repo }} ${{ steps.detect.outputs.new_tag }}. | |
| You are a fresh reviewer with no prior context from that | |
| session. Your job is purely editorial. | |
| Run /docs-review over every file the previous commit | |
| changed (use `git show --name-only HEAD` or `git diff | |
| --name-only HEAD~1 HEAD` to find them). Apply every | |
| actionable fix per the skill's standard guidance. | |
| If you spot a factual concern, re-verify against source | |
| code in the local clone at | |
| ${{ steps.clone.outputs.scratch_dir }} before changing | |
| anything. Don't introduce new claims; only refine what's | |
| already there. | |
| Do NOT re-run /upstream-release-docs. Do NOT touch files | |
| under docs/toolhive/reference/cli/, static/api-specs/, | |
| or docs/toolhive/reference/crds/ — those are | |
| regenerated from release assets and aren't yours to edit. | |
| - name: Capture skill signal files | |
| id: signals | |
| run: | | |
| GAPS_BODY="" | |
| NO_CHANGES_BODY="" | |
| if [ -f GAPS.md ]; then | |
| GAPS_BODY=$(cat GAPS.md) | |
| rm GAPS.md | |
| fi | |
| if [ -f NO_CHANGES.md ]; then | |
| NO_CHANGES_BODY=$(cat NO_CHANGES.md) | |
| rm NO_CHANGES.md | |
| fi | |
| # Build full markdown fragments here so the PR body edit | |
| # step can treat them as plain strings. | |
| { | |
| echo "note_block<<NOTE_EOF" | |
| if [ -n "$NO_CHANGES_BODY" ]; then | |
| echo "> [!NOTE]" | |
| echo "> The skill reported no doc-relevant changes for this" | |
| echo "> release. This PR only bumps the version reference" | |
| echo "> and any pin_files substitutions." | |
| echo ">" | |
| echo "> $NO_CHANGES_BODY" | |
| fi | |
| echo "NOTE_EOF" | |
| echo "gaps_block<<GAPS_EOF" | |
| if [ -n "$GAPS_BODY" ]; then | |
| echo "## Gaps needing human context" | |
| echo "" | |
| echo "$GAPS_BODY" | |
| fi | |
| echo "GAPS_EOF" | |
| } >> "$GITHUB_OUTPUT" | |
| - name: Apply pin_files substitutions | |
| env: | |
| PROJECT_ID: ${{ steps.detect.outputs.id }} | |
| NEW_TAG: ${{ steps.detect.outputs.new_tag }} | |
| run: | | |
| node scripts/upstream-release/apply-pin-files.mjs \ | |
| --id "$PROJECT_ID" \ | |
| --tag "$NEW_TAG" | |
| - name: Detect touches to auto-generated paths | |
| id: autogen | |
| # Runs AFTER the skill and AFTER the refresh commit above, so | |
| # the staged diff represents skill-introduced changes only. | |
| run: | | |
| git add -A | |
| TOUCHED=$(git diff --cached --name-only -- \ | |
| 'docs/toolhive/reference/cli/' \ | |
| 'static/api-specs/' \ | |
| 'docs/toolhive/reference/crds/' | paste -sd, - || true) | |
| { | |
| echo "note<<AUTOGEN_EOF" | |
| if [ -n "$TOUCHED" ]; then | |
| echo "> [!WARNING]" | |
| echo "> The skill touched files under auto-generated paths:" | |
| echo "> \`$TOUCHED\`" | |
| echo ">" | |
| echo "> These paths are synced or regenerated from release" | |
| echo "> assets earlier in this workflow. Review the skill's" | |
| echo "> changes and revert them if they should come from the" | |
| echo "> refresh step instead." | |
| fi | |
| echo "AUTOGEN_EOF" | |
| } >> "$GITHUB_OUTPUT" | |
| - name: Commit and push | |
| id: push | |
| env: | |
| PROJECT_ID: ${{ steps.detect.outputs.id }} | |
| NEW_TAG: ${{ steps.detect.outputs.new_tag }} | |
| HEAD_REF: ${{ steps.eff.outputs.head_ref }} | |
| run: | | |
| # Stage any skill content and add a content commit if non-empty. | |
| git add -A | |
| if ! git diff --cached --quiet; then | |
| git commit -m "Add upstream-release-docs content for $PROJECT_ID $NEW_TAG" | |
| else | |
| echo "No skill content changes to commit." | |
| fi | |
| # Skill can take 20-45 min; during that window someone may | |
| # push merges-from-main or other commits to the PR branch. | |
| # Handle that safely: | |
| # - If our local HEAD is already on origin (no new work | |
| # to push), exit cleanly. | |
| # - Otherwise rebase any local-only commits onto the | |
| # latest origin tip, then push. Conflicts fail loudly. | |
| git fetch origin "$HEAD_REF" --quiet | |
| if git merge-base --is-ancestor HEAD "origin/$HEAD_REF" 2>/dev/null; then | |
| echo "Origin is at or ahead of local; nothing to push." | |
| else | |
| git rebase "origin/$HEAD_REF" || { | |
| echo "::error::Rebase of local commits onto origin/$HEAD_REF hit conflicts. Resolve manually on the PR branch." | |
| exit 1 | |
| } | |
| git push origin "HEAD:$HEAD_REF" | |
| fi | |
| - name: Augment PR body (marker-delimited section) | |
| # Runs even if earlier steps soft-failed so the augmentation | |
| # survives partial failures; a subsequent workflow_dispatch | |
| # retry will re-enter here. | |
| if: always() && steps.detect.outputs.id != '' | |
| env: | |
| PR_NUMBER: ${{ steps.eff.outputs.number }} | |
| PROJECT_ID: ${{ steps.detect.outputs.id }} | |
| NEW_TAG: ${{ steps.detect.outputs.new_tag }} | |
| PREV_TAG: ${{ steps.detect.outputs.prev_tag }} | |
| REPO: ${{ steps.detect.outputs.repo }} | |
| NOTE_BLOCK: ${{ steps.signals.outputs.note_block }} | |
| GAPS_BLOCK: ${{ steps.signals.outputs.gaps_block }} | |
| AUTOGEN_NOTE: ${{ steps.autogen.outputs.note }} | |
| COMPARE_OK: ${{ steps.reviewers.outputs.compare_ok }} | |
| run: | | |
| START='<!-- upstream-release-docs:start -->' | |
| END='<!-- upstream-release-docs:end -->' | |
| # Build our section. | |
| { | |
| echo "$START" | |
| echo "" | |
| echo "## Content additions by upstream-release-docs" | |
| echo "" | |
| echo "Source-verified against \`$REPO\` at tag \`$NEW_TAG\` (was \`$PREV_TAG\`). The \`upstream-release-docs\` and \`docs-review\` skills each ran twice (three total passes) before this update." | |
| echo "" | |
| if [ "$COMPARE_OK" != "true" ]; then | |
| echo "> [!WARNING]" | |
| echo "> Could not compare \`$PREV_TAG\` against \`$NEW_TAG\` upstream, so no reviewers were auto-assigned from release contributors. The pinned previous tag may have been retagged or deleted." | |
| echo "" | |
| fi | |
| if [ -n "$NOTE_BLOCK" ]; then | |
| echo "$NOTE_BLOCK" | |
| echo "" | |
| fi | |
| if [ -n "$AUTOGEN_NOTE" ]; then | |
| echo "$AUTOGEN_NOTE" | |
| echo "" | |
| fi | |
| echo "### Review guidance" | |
| echo "" | |
| echo "Machine-generated reference files under \`docs/toolhive/reference/cli/\`, \`static/api-specs/\`, and \`docs/toolhive/reference/crds/\` are synced or regenerated from upstream release assets (separate commit, titled \"Refresh reference assets\") and should be spot-checked only. The \"Add upstream-release-docs content\" commit contains hand-edited prose; review that one for accuracy, not just style. If the \"Gaps needing human context\" section is populated, the skill deferred those sections to a human; fill them in before merging." | |
| echo "" | |
| if [ -n "$GAPS_BLOCK" ]; then | |
| echo "$GAPS_BLOCK" | |
| echo "" | |
| fi | |
| echo "Reviewers below are non-bot commit authors in the release range who are also collaborators on this repo." | |
| echo "" | |
| echo "$END" | |
| } > /tmp/section.md | |
| # Read existing body, replace or append our marked section. | |
| EXISTING=$(gh pr view "$PR_NUMBER" --json body --jq .body) | |
| if echo "$EXISTING" | grep -qF "$START"; then | |
| # Replace existing section. | |
| printf '%s\n' "$EXISTING" | awk -v start="$START" -v end="$END" -v repl_file=/tmp/section.md ' | |
| BEGIN { in_section = 0 } | |
| $0 == start { in_section = 1; while ((getline line < repl_file) > 0) print line; next } | |
| $0 == end { if (in_section) { in_section = 0; next } } | |
| !in_section { print } | |
| ' > /tmp/pr-body.md | |
| else | |
| # Append. | |
| { | |
| printf '%s\n\n---\n\n' "$EXISTING" | |
| cat /tmp/section.md | |
| } > /tmp/pr-body.md | |
| fi | |
| gh pr edit "$PR_NUMBER" --body-file /tmp/pr-body.md | |
| - name: Add reviewers | |
| if: always() && steps.reviewers.outputs.list != '' | |
| env: | |
| PR_NUMBER: ${{ steps.eff.outputs.number }} | |
| REVIEWERS: ${{ steps.reviewers.outputs.list }} | |
| run: gh pr edit "$PR_NUMBER" --add-reviewer "$REVIEWERS" | |
| - name: Comment on augmentation failure | |
| # Runs only when a preceding step failed. Comments a retry | |
| # pointer on the PR so a human can see the run URL. | |
| if: failure() | |
| env: | |
| PR_NUMBER: ${{ steps.eff.outputs.number }} | |
| RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} | |
| run: | | |
| gh pr comment "$PR_NUMBER" --body "Automated docs augmentation failed. Run: $RUN_URL | |
| Retry via the \`Upstream Release Docs\` workflow with \`pr_number=$PR_NUMBER\` once the underlying issue is resolved." || true |