feat: add rpk documentation automation

[JakeSCahill]

Summary

Add the infrastructure for automated rpk CLI documentation generation. Does not include generated pages - those will be created by running the workflow after merge.

Dependencies

Requires: redpanda-data/docs-extensions-and-macros#203 - The rpk-docs generator tool

What's included

GitHub Action workflow

.github/workflows/update-rpk-docs.yml - Automated documentation updates:

• Manual trigger: Run from GitHub Actions UI with version selection
• Cross-repo trigger: Can be invoked from rpk releases via repository_dispatch
• Automatic PRs: Creates PRs with detailed diff summaries showing new/removed commands and flags

Writer override system

docs-data/rpk-overrides.json - Customize auto-generated content:

• Description overrides and improvements
• Structured examples with output blocks
• Custom sections, admonitions, and includes
• Flag description enhancements
• Cross-references via seeAlso links
• Command exclusions (rpk ai, rpk oxla)

Documentation

• docs-data/RPK_OVERRIDES_GUIDE.adoc - Complete guide for writers
• docs-data/README.adoc - Directory reference
• docs-data/rpk-overrides.schema.json - JSON Schema for editor validation

Excluded commands

The following commands are excluded from generation (marked "coming soon"):

• rpk ai * - 41 commands
• rpk oxla - 1 command

Usage after merge

Generate docs via workflow:

1. Go to Actions → "Update rpk Documentation"
2. Click "Run workflow"
3. Enter version (e.g., v26.2.0 or dev)
4. Review and merge the auto-generated PR

Generate docs locally:

npx doc-tools generate rpk-docs --branch dev --fetch-binary

Test plan

• Workflow validates with act dry run
• Overrides include excludes for rpk ai and rpk oxla
• Schema validates correctly
• Run workflow after merge to generate initial pages

[netlify]

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	33f6a04
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/6a2acf8b5883f600089d33eb
😎 Deploy Preview	https://deploy-preview-1733--redpanda-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7dd4b718-d613-48df-88fb-99b592010930

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR introduces a complete system for customizing auto-generated rpk CLI documentation through JSON-based overrides. It adds a directory structure guide, a comprehensive JSON Schema defining the override format, a detailed user guide explaining how to use overrides, and a GitHub Actions workflow that automates documentation generation and pull request creation with parsed diff summaries.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• redpanda-data/docs#1097: Both PRs modify GitHub Actions workflows to automate pull-request creation using peter-evans/create-pull-request for documentation updates.

Suggested reviewers

• paulohtb6
• micheleRP
• r-vasquez
• kbatuigas

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: add rpk documentation automation' clearly and concisely summarizes the main change: adding infrastructure for automated rpk CLI documentation generation.
Description check	✅ Passed	The description is comprehensive and well-structured, covering objectives, dependencies, included files, excluded commands, usage instructions, and a test plan—substantially exceeding the template requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/rpk-docs-automation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

.github/workflows/update-rpk-docs.yml (1)

30-30: ⚡ Quick win

Pin GitHub Actions to commit SHAs for supply chain security.

Actions are referenced by mutable tags (@v4, @v5, @v6) which can be updated by action maintainers. Pinning to immutable commit SHAs prevents supply chain attacks where action tags are compromised.

Example pins for current stable versions:

• actions/checkout@v4 → actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
• actions/setup-node@v4 → actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
• actions/setup-go@v5 → actions/setup-go@3041bf56c941b39c61721a86cd11f3bb1338122a # v5.2.0
• peter-evans/create-pull-request@v6 → peter-evans/create-pull-request@5e914681df9dc83aa4e4905692ca88beb2f9e91f # v7.0.5

Verify current SHA pins before applying.

Also applies to: 35-35, 44-44, 210-210

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/update-rpk-docs.yml at line 30, The workflow references
mutable action tags like actions/checkout@v4, actions/setup-node@v4,
actions/setup-go@v5, and peter-evans/create-pull-request@v6; replace those tag
references with their corresponding immutable commit SHAs (e.g.,
actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683,
actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af,
actions/setup-go@3041bf56c941b39c61721a86cd11f3bb1338122a,
peter-evans/create-pull-request@5e914681df9dc83aa4e4905692ca88beb2f9e91f) and
verify the current stable SHA for each action before applying the change so the
workflow uses immutable pins for supply-chain security.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/update-rpk-docs.yml:
- Around line 29-32: The checkout step labeled "Checkout docs repo" (uses:
actions/checkout@v4) is missing persist-credentials control; modify that step to
add persist-credentials: false under its with block to ensure the GITHUB_TOKEN
is not persisted to the checked-out repo and cannot leak to subsequent steps or
git operations.
- Around line 48-71: The step is vulnerable because it directly interpolates
user-controlled inputs into shell assignments (VERSION, DIFF_VERSION,
DRAFT_MISSING, branch_name); instead validate and sanitize those inputs before
use: explicitly read the incoming values into safe variables, validate VERSION
against an allowlist/regex (e.g. semantic version or "dev"), normalize/whitelist
DIFF_VERSION and DRAFT_MISSING (accept only expected patterns like digits or
"true"/"false"), and reject or fallback to safe defaults for anything else;
construct branch_name from the validated VERSION only (no raw string
concatenation of untrusted input) and prefer assigning values via the GitHub
Actions env/outputs mechanism rather than unquoted shell expansion so no user
payload can inject commands.
- Around line 102-107: Remove the redundant file-existence test that uses `[ -f
"docs-data/rpk-diff-*.json" ]`; instead keep the existing discovery using
`DIFF_FILE=$(ls -t docs-data/rpk-diff-*.json 2>/dev/null | head -1)` and the
subsequent `if [ -n "$DIFF_FILE" ]; then echo "diff_file=$DIFF_FILE" >>
$GITHUB_OUTPUT; fi` logic so the script relies on `ls` to find the latest
matching `docs-data/rpk-diff-*.json` file and only emits to `GITHUB_OUTPUT` when
`DIFF_FILE` is non-empty (remove the outer `if [ -f ... ]; then` and its
matching `fi`).

---

Nitpick comments:
In @.github/workflows/update-rpk-docs.yml:
- Line 30: The workflow references mutable action tags like actions/checkout@v4,
actions/setup-node@v4, actions/setup-go@v5, and
peter-evans/create-pull-request@v6; replace those tag references with their
corresponding immutable commit SHAs (e.g.,
actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683,
actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af,
actions/setup-go@3041bf56c941b39c61721a86cd11f3bb1338122a,
peter-evans/create-pull-request@5e914681df9dc83aa4e4905692ca88beb2f9e91f) and
verify the current stable SHA for each action before applying the change so the
workflow uses immutable pins for supply-chain security.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2516b58b-06c0-462f-88ec-8c6809c42486

📥 Commits

Reviewing files that changed from the base of the PR and between 0a37226 and 9c868ee.

📒 Files selected for processing (5)

• .github/workflows/update-rpk-docs.yml
• docs-data/README.adoc
• docs-data/RPK_OVERRIDES_GUIDE.adoc
• docs-data/rpk-overrides.json
• docs-data/rpk-overrides.schema.json

[Feediver1]

PR Review

Files reviewed: 2 .adoc writer guides + 1 workflow + 2 JSON files (1 data, 1 schema)
Overall assessment: Well-scoped infrastructure PR that ships only the automation harness, not the 200+ pages it'll regenerate. The plan is sound, but the writer guide has stale paths from when it lived in docs-extensions-and-macros, and CodeRabbit has caught a real security issue in the workflow.

What this PR does

Adds the infrastructure to automatically generate rpk CLI documentation: a GitHub Actions workflow (triggerable manually or via repository_dispatch from rpk releases), a writer-facing override system (rpk-overrides.json + JSON Schema), and two writer guides (README.adoc and RPK_OVERRIDES_GUIDE.adoc). The override system lets writers customize the generated pages — adding examples, admonitions, sections, cross-references, deprecation notices — without modifying source code. rpk ai (41 commands) and rpk oxla are explicitly excluded with "coming soon" notes.

Jira ticket alignment

Ticket: Not referenced directly in the PR title/body. Linked dependency is docs-extensions-and-macros#203 ("DOC-2220: comprehensive rpk documentation automation system"), which is still OPEN, not merged.
Status: The infrastructure addresses the docs-side half of DOC-2220. The runtime dependency (npx doc-tools generate rpk-docs) lives in #203 and must merge before this PR's workflow can actually function. Worth coordinating merge order.

Critical issues (must fix)

1. docs-data/RPK_OVERRIDES_GUIDE.adoc:17 — Wrong file location. The guide says the override file is at docs-extensions-and-macros/docs-data/rpk-overrides.json, but this PR adds it to docs/docs-data/rpk-overrides.json. Writers following the guide will look in the wrong repo.

   • Fix: Update to the actual path: docs-data/rpk-overrides.json (relative to the docs repo root).

2. docs-data/RPK_OVERRIDES_GUIDE.adoc:432 — Outdated command example. Shows --output-dir ../docs/modules/reference/pages/rpk (assumes the writer is running from docs-extensions-and-macros). From the docs repo it should be just --output-dir modules/reference/pages/rpk.

   • Fix: Drop the ../docs/ prefix to match the new file location.

3. docs-data/RPK_OVERRIDES_GUIDE.adoc:514-515 — "Related resources" links point to ../tools/rpk-docs/README.adoc and ../CLAUDE.md — both relative paths that only make sense from the docs-extensions-and-macros repo root. From this repo, both 404.

   • Fix: Either drop these or replace with the correct cross-repo URLs (e.g., https://github.com/redpanda-data/docs-extensions-and-macros/blob/main/tools/rpk-docs/README.adoc).

4. .github/workflows/update-rpk-docs.yml:53-59 — Template injection vulnerability flagged by CodeRabbit. repository_dispatch payload values (github.event.client_payload.version etc.) are directly expanded into shell commands. Anyone with cross-repo dispatch privileges could inject arbitrary shell. Real security concern, not a hypothetical.

   • Fix: Move payload values into an env: block on the step and reference them via $VERSION shell vars (which respects shell quoting), instead of expanding ${{ … }} directly inside the run: script.

Suggestions (should consider)

1. docs-data/README.adoc:18, 100 — xref:docs-data/RPK_OVERRIDES_GUIDE.adoc[…] won't resolve as an Antora xref because docs-data/ isn't an Antora module — it's a repo data directory. Should be a relative file link for GitHub viewing.

   • Current: xref:docs-data/RPK_OVERRIDES_GUIDE.adoc[…]
   • Suggested: link:RPK_OVERRIDES_GUIDE.adoc[…]

2. .github/workflows/update-rpk-docs.yml:32 (CodeRabbit) Set persist-credentials: false on the actions/checkout@v4 step. Prevents the GITHUB_TOKEN from leaking into subsequent steps or git operations.

3. Workflow, all actions (CodeRabbit nitpick) Pin actions to commit SHAs (actions/checkout@<sha>) instead of tags. Supply-chain hardening; lower urgency than the injection fix but worth doing once.

4. .github/workflows/update-rpk-docs.yml around line 102 (CodeRabbit) [ -f "docs-data/rpk-diff-*.json" ] doesn't expand wildcards in a -f test. The ls -t line below it does the real work; the [ -f … ] guard is dead code. Remove it.

5. Verify before merge — The PR description checkbox "Run workflow after merge to generate initial pages" is unchecked. Confirm the plan: this PR adds infrastructure, then a follow-up automated PR will land the actual generated pages. Make sure that follow-up PR's first run is reviewed carefully — it will replace 221 existing rpk-*.adoc files at once.

Impact on other files

• modules/reference/pages/rpk/ (221 existing .adoc files) — Will be regenerated/replaced by the first workflow run after merge. No nav update needed (filenames preserved), but the diff on that follow-up PR will be massive. Worth flagging in the review thread so the reviewer knows what to expect.
• a99a1e4a feat: auto-update what's-new with rpk CLI changes (commit in this PR) — implies the workflow writes to a What's New file. Verify the workflow targets the right release-notes page.
• Dependency: docs-extensions-and-macros#203 — must merge before this PR's workflow can run successfully. The workflow's npx doc-tools generate rpk-docs won't resolve until that lands.
• No nav.adoc update needed. No What's New entry needed (this is infrastructure, not a customer-facing feature).

CodeRabbit findings worth considering

All four are surfaced above. The template injection one (critical) is the most important — that's a real CI security issue, not a style preference. The other three (persist-credentials, action SHA pinning, redundant -f test) are smaller hardening / code-quality wins that I'd bundle into the same revision.

What works well

• Right scope for a "land it" PR. Ships the harness, not the 200+ generated pages — reviewers can evaluate the system itself without rubber-stamping a massive diff.
• Per-subcommand explicit exclusion for rpk ai (each of 41 subcommands listed individually) instead of a wildcard. Easier to un-exclude individual commands as features ship.
• Schema-driven authoring. The JSON Schema gives writers VS Code autocomplete and validation — high authoring quality of life for non-engineers.
• Override taxonomy is comprehensive. Sections, admonitions, examples, includes, $ref reuse, flag-level enhancements, deprecation, platform restrictions, see-also links, text transformations — clearly thought through.
• RC handling logic. The auto-targeting of the beta branch for -rcN versions (workflow lines 91-114) is exactly the kind of edge-case handling that prevents on-call surprises.
• Cross-repo dispatch. Lets rpk releases push docs updates without manual work.
• Clear writer-editable / generated boundary in README.adoc.

---

🤖 Generated with Claude Code via /docs-team-standards:pr-review