From 8514f2bad200435eaec175b6f4b3516e09276fce Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Fri, 31 Jul 2026 11:43:06 +0100 Subject: [PATCH] ci: re-render rpk docs when the overrides file changes The overrides file is the curated-content store for generated rpk pages, but nothing regenerated the pages when it changed: an overrides edit merged and the rendered docs kept the old content until the next release-driven regeneration. docs#1862 made this visible by fixing dozens of overrides whose pages will not update until the next release regen runs. New workflow triggers on pushes to main or beta that touch docs-data/rpk-overrides.json or its schema, re-renders the full rpk tree from the newest committed snapshot (pure from-json render: no rpk binary, no diff, no What's new), and opens a PR with the changed pages using the actions bot token so checks run. Idempotent no-op runs exit green without a PR, and the PR only touches generated pages so it cannot re-trigger the workflow. --- .../rerender-rpk-docs-on-overrides-change.yml | 123 ++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 .github/workflows/rerender-rpk-docs-on-overrides-change.yml diff --git a/.github/workflows/rerender-rpk-docs-on-overrides-change.yml b/.github/workflows/rerender-rpk-docs-on-overrides-change.yml new file mode 100644 index 0000000000..94c24dc28a --- /dev/null +++ b/.github/workflows/rerender-rpk-docs-on-overrides-change.yml @@ -0,0 +1,123 @@ +# Re-renders the generated rpk reference pages whenever the overrides file +# changes on a docs branch. +# +# The overrides file (docs-data/rpk-overrides.json) is the curated-content +# store for generated rpk pages: descriptions, flag rewrites, added sections, +# exclusions. Without this workflow, an overrides edit merges but the rendered +# pages keep the old content until the next release-driven regeneration, so +# the repo carries overrides that the published docs do not reflect. +# +# This is a pure re-render from the newest committed rpk snapshot: no rpk +# binary, no diff, no What's new update. The run is idempotent, so a re-render +# that changes nothing exits green without opening a PR. The PR only touches +# generated pages, which cannot re-trigger this workflow (it only watches the +# overrides file and its schema). +name: Re-render rpk docs on overrides change + +on: + push: + branches: [main, beta] + paths: + - 'docs-data/rpk-overrides.json' + - 'docs-data/rpk-overrides.schema.json' + workflow_dispatch: + +permissions: + contents: write + pull-requests: write + id-token: write + +# Only the newest overrides state matters: a superseded run for the same +# branch is cancelled rather than queued. +concurrency: + group: rpk-overrides-rerender-${{ github.ref_name }} + cancel-in-progress: true + +jobs: + rerender: + runs-on: ubuntu-latest + timeout-minutes: 20 + steps: + - name: Checkout docs repo + uses: actions/checkout@v4 + with: + ref: ${{ github.ref_name }} + persist-credentials: false + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Resolve newest rpk snapshot + id: snapshot + run: | + # Tilde-normalize prerelease suffixes first: plain sort -V ranks + # 26.2.1-rc2 above 26.2.1, which would re-render GA pages from an + # RC snapshot. + SNAPSHOT=$(ls docs-data/rpk-v*.json 2>/dev/null | grep -v 'rpk-diff' | sed 's/-rc/~rc/' | sort -V | sed 's/~rc/-rc/' | tail -1) + if [ -z "$SNAPSHOT" ]; then + echo "::error::No rpk snapshot found in docs-data/" + exit 1 + fi + echo "Using snapshot: $SNAPSHOT" + echo "snapshot=$SNAPSHOT" >> "$GITHUB_OUTPUT" + + - name: Re-render rpk docs + run: | + npx --yes -p @redpanda-data/docs-extensions-and-macros@^5.3.0 doc-tools generate rpk-docs \ + --from-json "${{ steps.snapshot.outputs.snapshot }}" \ + --summary-file /tmp/pr-summary.md + + - name: Detect changes + id: changes + run: | + if [ -n "$(git status --porcelain)" ]; then + echo "has_changes=true" >> "$GITHUB_OUTPUT" + git status --short | head -20 + else + echo "has_changes=false" >> "$GITHUB_OUTPUT" + echo "Overrides change did not alter any rendered page. Nothing to do." + fi + + - name: Configure AWS credentials + if: steps.changes.outputs.has_changes == 'true' + uses: aws-actions/configure-aws-credentials@v4 + with: + aws-region: ${{ vars.RP_AWS_CRED_REGION }} + role-to-assume: arn:aws:iam::${{ secrets.RP_AWS_CRED_ACCOUNT_ID }}:role/${{ vars.RP_AWS_CRED_BASE_ROLE_NAME }}${{ github.event.repository.name }} + + - name: Fetch actions bot token + if: steps.changes.outputs.has_changes == 'true' + uses: aws-actions/aws-secretsmanager-get-secrets@v2 + with: + secret-ids: | + ,sdlc/prod/github/actions_bot_token + parse-json-secrets: true + + - name: Build PR body + if: steps.changes.outputs.has_changes == 'true' + run: | + { + echo "Automated re-render of the generated rpk reference pages after an overrides change on \`${{ github.ref_name }}\` (${{ github.sha }})." + echo + echo "Review focus: the changed pages should reflect exactly the merged overrides edit, nothing else. The generator version is pinned to the same range the release regeneration uses, so unrelated churn here means the branch missed a regeneration and this PR is catching it up." + echo + cat /tmp/pr-summary.md 2>/dev/null || true + } > /tmp/pr-body.md + + - name: Create Pull Request + if: steps.changes.outputs.has_changes == 'true' + uses: peter-evans/create-pull-request@v6 + with: + token: ${{ env.ACTIONS_BOT_TOKEN }} + branch: rpk-docs/overrides-rerender-${{ github.ref_name }} + base: ${{ github.ref_name }} + title: 'docs: re-render rpk docs for overrides change (${{ github.ref_name }})' + body-path: /tmp/pr-body.md + commit-message: 'docs: re-render rpk docs for overrides change' + labels: | + documentation + automated + rpk + delete-branch: true