Skip to content

test: add Doc Detective coverage for the Kind local development guide #1851

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
JakeSCahill wants to merge 1 commit into from
Closed

test: add Doc Detective coverage for the Kind local development guide #1851

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 73 additions & 0 deletions .github/workflows/test-docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ jobs:
outputs:
console: ${{ steps.filter.outputs.console }}
quickstart: ${{ steps.filter.outputs.quickstart }}
kindguide: ${{ steps.filter.outputs.kindguide }}
steps:
- name: Checkout code
uses: actions/checkout@v4
Expand All @@ -26,6 +27,10 @@ jobs:
- 'modules/console/**'
quickstart:
- 'modules/get-started/pages/quick-start.adoc'
kindguide:
- 'modules/deploy/pages/redpanda/kubernetes/local-guide.adoc'
- 'modules/deploy/partials/kubernetes/**'
- 'antora.yml'
Comment on lines +30 to +33

@coderabbitai coderabbitai Bot Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Include the rpk installation partial in this filter.

local-guide.adoc includes get-started:partial$install-rpk-linux.adoc at Line 540, but this filter only watches the local guide, Kubernetes partials, and antora.yml. Changes to the rpk installation instructions can therefore break the guide without running test-kind-guide.

Suggested filter update 
             kindguide:
               - 'modules/deploy/pages/redpanda/kubernetes/local-guide.adoc'
               - 'modules/deploy/partials/kubernetes/**'
+              - 'modules/get-started/partials/install-rpk-linux.adoc'
               - 'antora.yml'
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
kindguide:
- 'modules/deploy/pages/redpanda/kubernetes/local-guide.adoc'
- 'modules/deploy/partials/kubernetes/**'
- 'antora.yml'
kindguide:
- 'modules/deploy/pages/redpanda/kubernetes/local-guide.adoc'
- 'modules/deploy/partials/kubernetes/**'
- 'modules/get-started/partials/install-rpk-linux.adoc'
- 'antora.yml'
🧰 Tools
🪛 zizmor (1.28.0)

[warning] 12-33: overly broad permissions (excessive-permissions): default permissions used due to no permissions: block

(excessive-permissions)

🤖 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/test-docs.yml around lines 30 - 33, Update the kindguide
path filter in the test-docs workflow to include the rpk installation partial
referenced by local-guide.adoc, ensuring changes to that partial trigger
test-kind-guide alongside the existing guide, Kubernetes partial, and antora.yml
paths.


run-tests:
needs: setup
Expand Down Expand Up @@ -98,3 +103,71 @@ jobs:
path: /home/runner/work/_temp/doc-detective-output.json
env:
REDPANDA_GITHUB_TOKEN: ${{ env.ACTIONS_BOT_TOKEN }}

test-kind-guide:
needs: setup
# Skip the entire job for fork PRs. Run for all scheduled and manual triggers, and on PRs that touch the Kind guide or its shared partials.
if: >-
(github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork != true) &&
(github.event_name == 'workflow_dispatch' || github.event_name == 'repository_dispatch' || github.event_name == 'schedule' || needs.setup.outputs.kindguide == 'true')
permissions:
contents: write
pull-requests: write
issues: write
id-token: write
runs-on: ubuntu-latest
timeout-minutes: 45
Comment on lines +118 to +119

@coderabbitai coderabbitai Bot Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Increase the job timeout.

The guide permits 21 minutes for Redpanda readiness, 11 minutes for broker deletion, and additional 5-minute installation waits plus teardown. A healthy but slow run can exceed 45 minutes and be killed before cleanup. Increase the job timeout or reduce the individual budgets.

🤖 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/test-docs.yml around lines 118 - 119, Increase the
timeout-minutes value for the workflow job using runs-on ubuntu-latest so it
accommodates the documented Redpanda readiness, broker deletion, installation
waits, and teardown budgets without premature cancellation.

steps:
- 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 }}
- uses: aws-actions/aws-secretsmanager-get-secrets@v2
with:
secret-ids: |
,sdlc/prod/github/actions_bot_token
parse-json-secrets: true
- uses: actions/checkout@v4
with:
token: ${{ env.ACTIONS_BOT_TOKEN }}
path: redpanda-docs
Comment on lines +121 to +133

@coderabbitai coderabbitai Bot Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🔴 Critical | 🏗️ Heavy lift

🧩 Analysis chain

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail
rg -n -C2 'configure-aws-credentials|aws-secretsmanager|GITHUB_ENV|persist-credentials' \
  .github/workflows/test-docs.yml

Repository: redpanda-data/docs

Length of output: 1427

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

echo "== workflow size =="
wc -l .github/workflows/test-docs.yml

echo "== relevant sections =="
sed -n '1,190p' .github/workflows/test-docs.yml | cat -n

echo "== commands/runs in workflow =="
rg -n '(^ *(run|environment):\s*|^\s+- name:|configure-aws-credentials|aws-secretsmanager|GITHUB_ENV|persist-credentials|chmod|npm install|run:)' .github/workflows/test-docs.yml

Repository: redpanda-data/docs

Length of output: 9059

🌐 Web query:

aws-actions/aws-secretsmanager-get-secrets @v2 secret environment variables documentation

💡 Result:

The aws-actions/aws-secretsmanager-get-secrets @v2 action allows you to retrieve secrets from AWS Secrets Manager and inject them into your GitHub Actions workflow as environment variables [1][2][3]. Key behavior and configuration options for environment variables include: Default Naming Behavior By default, the action generates environment variable names based on the secret name [1][2]. These names are automatically transformed to contain only uppercase letters, numbers, and underscores, and are ensured not to begin with a number [1][2]. Custom Naming You can define a custom environment variable name by specifying it before the secret ID, separated by a comma (e.g., ENV_VAR_NAME, secretId) [1][2]. Custom names must consist only of uppercase letters, numbers, and underscores [1][2]. Name Transformation The name-transformation input allows you to control the case of the generated environment variable names [1][2]. - uppercase (default): Transforms names to uppercase [1][2]. - lowercase: Transforms names to lowercase [1][2]. - none: Keeps the name as provided (or as it appears in the secret name, subject to valid naming constraints) [2]. JSON Secrets - By default (parse-json-secrets: false), the entire JSON string of the secret value is set as the environment variable value [1][2]. - When set to true (parse-json-secrets: true), the action parses the JSON and creates individual environment variables for each key-value pair found in the secret [1][2]. Note that if the JSON contains case-sensitive keys that would result in duplicate environment variable names (e.g., "name" and "Name"), this may cause conflicts [2]. Usage Example - name: Get Secrets uses: aws-actions/aws-secretsmanager-get-secrets@v2 with: secret-ids: | secretId1 MY_CUSTOM_VAR, secretId2 parse-json-secrets: true name-transformation: uppercase The action also supports using prefixes (e.g., dev*) to retrieve multiple secrets at once, provided you do not explicitly assign a custom variable name for those matched secrets [1][2].

Citations:

🌐 Web query:

github-actions checkout persist-credentials default true README

💡 Result:

In the GitHub Actions checkout action (actions/checkout), the persist-credentials input parameter controls whether the GitHub token or SSH key used for the repository checkout is configured in the local git configuration [1][2][3]. Key details regarding this parameter include: Default Value: The default is true [1][2][3]. Function: When set to true (default), the credentials are made available to the local git configuration [4][5]. This allows subsequent steps in your workflow job to execute authenticated git commands (such as git fetch or git push) without requiring additional setup [4][2][5]. Security Note: Because the credentials are stored in the git configuration, they are technically accessible to other steps in the same job [6]. The action automatically cleans up these credentials during the post-job phase [4][7]. Opt-out: To disable this behavior for security reasons or if you do not require authenticated git commands in later steps, you can explicitly set persist-credentials: false in your workflow step [4][2][6]. Recent Improvements: In recent versions (such as v6.0.2), credential storage has been improved to store these credentials in a separate file under $RUNNER_TEMP rather than directly within the.git/config file, enhancing security while maintaining existing functionality [5].

Citations:

Do not expose AWS and write permissions to Doc Detective commands.

Both run-tests and test-kind-guide provision AWS credentials, fetch the actions bot token, checkout with that token, install PR-controlled dependencies, and then invoke Doc Detective; the token is also written to GITHUB_ENV and checkout does not opt out of persisted credentials. Run checkout, npm install, and Doc Detective without secrets/write permissions, checkout with persist-credentials: false using no auth, and move issue creation to a separate trusted job.

🧰 Tools
🪛 zizmor (1.28.0)

[warning] 130-133: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false

(artipacked)

🤖 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/test-docs.yml around lines 121 - 133, Restrict the
run-tests and test-kind-guide jobs to unprivileged Doc Detective execution:
remove AWS credential setup, Secrets Manager token retrieval, and authenticated
checkout, configure actions/checkout with no token and persist-credentials
disabled, and avoid installing PR-controlled dependencies with secrets or write
access. Move any issue creation into a separate trusted job that runs only after
these tests and retains the required permissions and credentials.

Source: Linters/SAST tools


- name: Install kind
uses: helm/kind-action@v1
with:
install_only: true

- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'

- name: Install dependencies
run: npm install
working-directory: redpanda-docs

- name: Set GitHub token
run: |
echo "REDPANDA_GITHUB_TOKEN=${{ env.ACTIONS_BOT_TOKEN }}" >> $GITHUB_ENV

- name: Test Kind local development guide
uses: doc-detective/github-action@v1
with:
input: ../../modules/deploy/pages/redpanda/kubernetes/local-guide.adoc
working_directory: redpanda-docs/tests/setup-tests
exit_on_fail: true
create_issue_on_fail: true
issue_title: "Doc Detective failure: Kind local guide"
issue_labels: "doc-detective,kind-guide"
integrations: "claude"
prompt: "Investigate this Kind local development guide test failure. The test executes the commands documented in modules/deploy/pages/redpanda/kubernetes/local-guide.adoc and its shared partials (modules/deploy/partials/kubernetes/). Determine whether the failure is a docs bug (command drift vs the current operator/chart behavior), a product regression, or test environment flake, and propose the specific docs fix if applicable."
token: ${{ env.ACTIONS_BOT_TOKEN }}
env:
REDPANDA_GITHUB_TOKEN: ${{ env.ACTIONS_BOT_TOKEN }}

- name: Upload debug artifacts
if: failure()
uses: actions/upload-artifact@v4
with:
name: doc-detective-kind-guide-output
path: /home/runner/work/_temp/doc-detective-output.json
Loading
Loading