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

What's new updates and the diff baseline

The workflow updates the What's new page (modules/get-started/pages/release-notes/redpanda.adoc) and produces the PR change summary from a diff between the version being generated and a previous baseline.

• Diff base: when no diff_version is supplied (the usual case for the repository_dispatch trigger from an rpk release), the workflow defaults to antora.yml's full-version — the version the docs currently target. An explicitly supplied diff_version overrides it, and a self-diff is skipped.
• Baseline requirement: the generator diffs against a committed snapshot docs-data/rpk-<version>.json; it does not rebuild the old version from source. The snapshot is written and committed on every run, so it is available from the next run onward.

Important

The first run is expected to skip the diff. No docs-data/rpk-v*.json snapshots are committed yet, so the first run for any version logs a ::warning::, skips the What's new update, and just establishes the baseline. What's new and the change summary populate automatically from the next run.

Generating the 26.1 baseline depends on the json-tree flag being available in 26.1 (backport pending). Once it is, generate the baseline for the patch matching antora.yml full-version (currently 26.1.9 → docs-data/rpk-v26.1.9.json) so the lookup matches.

Test plan

• Workflow validates with act dry run

• Overrides include excludes for rpk ai and rpk oxla

• Schema validates correctly

• Diff-base resolution (antora.yml fallback, explicit override, self-diff guard, missing-snapshot skip) verified against the extracted step script

• PR-body assembly from the generator's --summary-file verified end to end

• Workflow validates with act dry run

• Overrides include excludes for rpk ai and rpk oxla

• Schema validates correctly

[netlify]

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	5abdec2
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/6a4bd27ae20dba0008c0f184
😎 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: b8370bd4-869e-45c9-9fcf-13da4a98f02b

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 | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description does not follow the required template structure with Jira ticket reference and page previews.	Add the Jira ticket reference (Resolves https://redpandadata.atlassian.net/browse/), review deadline field, and page preview section. Include relevant checkboxes indicating the type of change (New feature, Content gap, Support Follow-up, or Small fix).

✅ Passed checks (4 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.
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.}

[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

[JakeSCahill]

Thanks for the thorough review! Addressed all critical issues in 719f467:

Critical fixes:

• ✓ Fixed file location in RPK_OVERRIDES_GUIDE.adoc (removed docs-extensions-and-macros/ prefix)
• ✓ Fixed command path example (removed ../docs/ prefix)
• ✓ Replaced broken relative links with cross-repo GitHub URLs
• ✓ Fixed template injection vulnerability by moving repository_dispatch payload to env: block (prevents shell injection)
• ✓ Added persist-credentials: false to checkout step

Note on redundant glob test: Already fixed in a99a1e4 - the [ -f "docs-data/rpk-diff-*.json" ] test was removed.

Merge order: Confirmed - docs-extensions-and-macros#203 must merge first (contains the npx doc-tools generate rpk-docs implementation). This PR is infrastructure-only and won't run successfully until that dependency lands.

[kbatuigas]

@JakeSCahill let me know if this is valid:

The new schema and the committed overrides file are out of sync in ways that look merge-blocking.

1. The schema rejects the examples structure already used in rpk-overrides.json.
   At docs-data/rpk-overrides.schema.json, subsection requires content and does not allow items. But docs-data/rpk-overrides.json uses subsection objects with items arrays for structured examples. I validated this with AJV against the schema in this PR, and it fails immediately on rpk topic create.

2. The schema also rejects command-level keys that are present in the same file.
   The command schema at docs-data/rpk-overrides.schema.json only allows appendToDescription, while the overrides file uses descriptionAppend in several places, for example at docs-data/rpk-overrides.json. It also uses descriptionScope at docs-data/rpk-overrides.json, which is not defined in the schema either. Because additionalProperties is false at docs-data/rpk-overrides.schema.json, these entries are invalid.

This leaves the PR in a state where the documented/validated format does not match the actual overrides data. I’d fix this one of two ways before merge:

1. Update the schema to match the existing generator data model.
2. Migrate rpk-overrides.json to the schema’s shape and validate it in CI as part of this workflow.

[JakeSCahill]

@kbatuigas Good catch! I've fixed both issues:

Fixed in d5cfc54

1. Schema updated to match docs-extensions-and-macros - The schema in this PR was an older snapshot. I've synced it with the current version from docs-extensions-and-macros which includes:

   • descriptionScope property for conditional description scoping
   • exampleItem definition for reuse in subsections
   • items property in subsection (as an alternative to content)
   • anyOf constraint allowing either content or items in subsections

2. Property name fixed - Renamed descriptionAppend → appendToDescription in the overrides file to match the schema property name

Schema now validates successfully:

$ node -e "..." # validation script
Schema validation passed!

The schema matches the generator's expected data model in docs-extensions-and-macros.

[JakeSCahill]

@kbatuigas please take another look

[micheleRP]

Two notes from working through a rpk group typo fix (redpanda-data/redpanda#30898) against this new system:

1. A textTransformations override would be a clean docs-side fix for source typos. There's a doubled word ("than there are are total partitions") in the rpk group long help. The durable fix is at source (redpanda-data/redpanda#30898), but if we ever want a docs-side guard that survives regeneration before a source fix lands, the override system already supports it. For the record, the entry would look like:

{
  "description": "Fix doubled 'are' in rpk group description",
  "pattern": "than there are are total partitions",
  "replacement": "than there are total partitions",
  "flags": "g"
}

I scoped the pattern to the full phrase rather than \bare are\b on purpose, since textTransformations apply globally across all rpk pages. Not requesting this be added now (the source fix supersedes it) — just confirming the mechanism works for this class of problem.

2. Minor doc fix in RPK_OVERRIDES_GUIDE.adoc. The "File location" section points to docs-extensions-and-macros/docs-data/rpk-overrides.json, but this PR places the file at docs-data/rpk-overrides.json in the docs repo. Worth correcting so writers look in the right place.

[micheleRP]

Cross-linking for visibility: redpanda-data/adp-docs#110 is hand-adding 34 rpk ai command pages (a2a, run claude/codex, dcr, oauth-client revoke-tokens, the agent tree) to adp-docs.

That bumps into this PR's design: #1733 deliberately excludes rpk ai (41 commands) as "coming soon," and adp-docs has no rpk automation of its own (no update-rpk-docs.yml, no rpk-overrides.json, no docs-data snapshots) — so the rpk-ai/ subtree there is fully hand-maintained, and #110's pages were generated from the rpk dev branch (giving rpk-core global flags instead of the --rpai-* plugin flags).

Two things worth aligning on when you get a chance:

1. Ownership: should rpk ai docs stay in adp-docs with their own generation+overrides path (mirroring this workflow but scoped to rpk ai instead of excluding it), or eventually fold into this docs-repo automation?
2. Unblock: clean generation for these needs a released plugin (≥ v0.1.11) that ships the commands and renders rpk ai help — tracked in cloudv2#26990. Until then the exclude here is the right call.

No action needed on this PR — just flagging the connection so the rpk-ai path doesn't fall between the two repos.