Add README.md documentation for cmd/ tools#5259
Draft
Prucek wants to merge 1 commit into
Draft
Conversation
Contributor
|
Pipeline controller notification For optional jobs, comment This repository is configured in: automatic mode |
📝 WalkthroughWait, I need to redo this carefully. Every rangeId must appear exactly once. Let me redo the assignment properly. I keep making mistakes with duplicates. Let me be very systematic and assign each rangeId to exactly one layer. I still have duplicates (range_9c81fce0eca0 appears in two layers, range_797489b0b181 appears twice). Let me do a final clean pass — I'll list all 114 rangeIds and assign each exactly once. WalkthroughAll 70+ ChangesREADME Documentation Expansion
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested reviewers
✨ Finishing Touches🧪 Generate unit tests (beta)
|
openshift-ci
Bot
added
the
do-not-merge/work-in-progress
Contributor
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: Prucek The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
openshift-ci
Bot
added
the
approved
Prucek
changed the title
Add or update README.md files across all cmd/ directories with standardized documentation including what the tool does, how it works, flags, key files, and deployment info. Deployment sections verified against openshift/release manifests. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Prucek
force-pushed
the
rename-agents-to-readme
branch
from
f3bde1b to
f96265a
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 20
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (18)
cmd/private-org-sync/README.md (2)
121-200:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRefresh the old example to the current CLI.
The example still uses
--config-pathand--git-dir, but the new flags table documents--config-dirinstead. Please update or drop this example so it matches the current invocation.🤖 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 `@cmd/private-org-sync/README.md` around lines 121 - 200, The example commands in the README.md file use outdated CLI flags that do not match the current documentation. Update the first command example that currently uses --config-path and --git-dir flags to use --config-dir instead, making it consistent with the flags table documentation and the second example command which already uses the correct --config-dir flag. Ensure all example invocations reflect the current CLI interface.
76-97:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winBring the legacy deployment notes up to date.
This appendix still says missing destination repositories are ignored unconditionally and that merge-conflict divergence is silently tolerated. That conflicts with the new
--fail-on-missing-destination/ error-handling section above, so readers now get two different behavior contracts.🤖 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 `@cmd/private-org-sync/README.md` around lines 76 - 97, The deployment notes section still describes outdated behavior regarding missing destination repositories and merge conflict handling. Update this section to reflect the current implementation by removing the statement that missing destinations are unconditionally ignored and instead reference the `--fail-on-missing-destination` flag mentioned in the error-handling section above. Similarly, update the merge conflict statement to align with the current error-handling behavior documented elsewhere in the README to ensure consistency and clarity for readers about the actual tool behavior.cmd/branchingconfigmanagers/README.md (1)
254-345:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRemove the obsolete contract appendix.
The trailing contract/deployment block is still marked incomplete and leaves
TODO: What period. That undermines the new top-level docs and keeps unfinished guidance in the canonical README.🤖 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 `@cmd/branchingconfigmanagers/README.md` around lines 254 - 345, Remove the entire "Config Manager Contract" section from the README.md file, which includes all subsections from "## Config Manager Contract" through the end of the "Deploying New Config Managers" section. This section is incomplete and marked with NOTE and TODO comments that undermine the documentation. Delete all content related to the contract definition, product lifecycle data structure, requirements for config managers, and deployment instructions that follow the incomplete deployment note.cmd/config-brancher/README.md (1)
94-98:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUpdate the retained bump-mode section to match
--bump-release.The new summary/table uses
--bump-release, but this legacy block still documents--bump. That leaves two different flag names for the same mode. Please rewrite or remove this tail section so the README stays self-consistent.Proposed fix
- In the bumping mode, it moves the development branch to promote to the version in the `--bump` flag, enabling the + In bump mode (`--bump-release`), it moves the development branch to promote to the target version, enabling the promotion in the release branch that used to match the dev branch version and disabling promotion in the release branch that now matches the dev branch version.🤖 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 `@cmd/config-brancher/README.md` around lines 94 - 98, The "Bumping configuration" section in the README still references the `--bump` flag while the rest of the documentation uses `--bump-release`. Update this legacy section by replacing all instances of `--bump` with `--bump-release` to maintain consistency throughout the README, or alternatively consider removing or rewriting this section if the information is already adequately covered in the new summary/table using the correct flag name.cmd/autoowners/README.md (1)
106-107:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix the
--self-approveusage snippet.The usage block shows
-self-approve approved, but the flags table documents--self-approveas a boolean flag. That extra positional value is misleading and should be removed or regenerated from the actual CLI help.♻️ Suggested fix
- -self-approve approved + -self-approve🤖 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 `@cmd/autoowners/README.md` around lines 106 - 107, The usage snippet for the `--self-approve` flag in the README.md incorrectly shows `-self-approve approved` with a positional argument, but the flags table documents it as a boolean flag without any arguments. Remove the `approved` positional value from the usage example at line 106-107 so that it correctly shows `-self-approve` as a standalone boolean flag, or regenerate the usage documentation from the actual CLI help output to ensure consistency with the flag's actual implementation.cmd/sippy-config-generator/README.md (1)
65-97:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winTrim the legacy manual-run appendix.
The new spec-style sections already cover purpose, flow, flags, and deployment; this older block duplicates that guidance and makes the README harder to scan.
🤖 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 `@cmd/sippy-config-generator/README.md` around lines 65 - 97, Remove the legacy manual-run appendix section from the README that includes the Related, Example invocation, Commit the output, and Customization subsections. These sections duplicate information already covered in the newer spec-style sections of the documentation. Delete this entire block to improve the README's readability and reduce redundant guidance.cmd/testgrid-config-generator/README.md (1)
75-132:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRemove or rewrite the legacy appendix.
It repeats older manual-run guidance and conflicts with the new spec-style sections above, so readers get mixed instructions.
🤖 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 `@cmd/testgrid-config-generator/README.md` around lines 75 - 132, The legacy appendix section starting with "Note: Go 1.13 is required." and continuing through the end of the diff repeats older manual-run guidance and conflicts with the new spec-style sections above it, creating mixed instructions for readers. Remove this entire legacy appendix section or completely rewrite it to eliminate the duplication and conflicts with the newer documentation structure. The section includes the Go 1.13 note, build instructions using the go build command, the manual run example with testgrid-config-generator flags, and verification steps that appear to duplicate guidance from earlier in the document.cmd/ci-secret-bootstrap/README.md (1)
68-141:⚠️ Potential issue | 🟠 Major | ⚡ Quick winRemove the stale Bitwarden/kubeconfig section.
This block still documents the old Bitwarden mappings,
--bw-password-path/--bw-user, and kubeconfig-context targeting. That directly conflicts with the Vault/GSM model above and leaves the README with two different contracts.🤖 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 `@cmd/ci-secret-bootstrap/README.md` around lines 68 - 141, The "Args and config.yaml" section and the "Run" section of the README document the legacy Bitwarden/kubeconfig approach with outdated parameters like --bw-password-path, --bw-user, and context-based cluster targeting, which conflicts with the current Vault/GSM model described earlier in the documentation. Remove the entire section starting from "## Args and config.yaml" through the end of the "## Run" section (including the code example with the ci-secret-bootstrap command) to eliminate this documentation contradiction and provide a single, consistent contract for the tool's usage.cmd/ci-secret-generator/README.md (1)
72-125:⚠️ Potential issue | 🟠 Major | ⚡ Quick winDelete the legacy Bitwarden example.
The bottom half still shows Bitwarden item/attachment/password mappings and
--bw-*flags, but the new intro says generation uploads to Vault and optionally GSM. Users will follow the wrong CLI/config shape if this stays.🤖 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 `@cmd/ci-secret-generator/README.md` around lines 72 - 125, Remove the legacy Bitwarden documentation and examples from the README file. Delete the YAML configuration examples that show Bitwarden attribute and password mappings (the sections demonstrating password as an attribute name and field configurations), and remove the Run section that shows the Bitwarden CLI usage with flags like --bw-password-path and --bw-user. Replace these removed sections with documentation that reflects the current behavior of uploading secrets to Vault and optionally GSM instead, ensuring the CLI flags and configuration examples match the actual tool functionality.cmd/vault-secret-collection-manager/README.md (1)
98-139:⚠️ Potential issue | 🟠 Major | ⚡ Quick winRemove the old endpoint docs.
This legacy section still says
PATCH /secretcollection/:nameedits members, while the authoritative table above usesPUT /secretcollection/:name/members. Keeping both makes the API contract ambiguous.🤖 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 `@cmd/vault-secret-collection-manager/README.md` around lines 98 - 139, Remove the outdated endpoint documentation in the Endpoints section of the README that describes PATCH /secretcollection/:name for changing secret collection members. This endpoint documentation is inconsistent with the authoritative API contract which uses PUT /secretcollection/:name/members instead. Delete the bullet point containing the PATCH endpoint description to eliminate the ambiguity and keep only the correct current endpoint in the documentation.cmd/gsm-secret-sync/README.md (1)
72-125:⚠️ Potential issue | 🟠 Major | ⚡ Quick winRewrite the old Bitwarden usage block.
This legacy section still talks about Bitwarden entries and
--bw-password-path/--bw-user, which conflicts with the new Vault/GCP workflow described above. Please remove or replace it so the README doesn't advertise two incompatible backends.🤖 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 `@cmd/gsm-secret-sync/README.md` around lines 72 - 125, Remove the legacy Bitwarden usage block from the README that contains references to `--bw-password-path` and `--bw-user` flags, as it conflicts with the new GCP and Vault workflow documented in the current sections. Search the entire file for any mentions of Bitwarden-related configuration, flags, environment variables, or usage examples and delete them completely to ensure the README only documents the current GCP-based backend and doesn't advertise incompatible or deprecated functionality.cmd/ocp-build-data-enforcer/README.md (1)
54-67:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRewrite the deployment bullets.
This section reads like a blend of two tools:
ocp-build-data-enforceris config-driven and works from fetched Dockerfiles, but it does not iterate a fixedopenshift-4.21/imagestree or directly edit Dockerfiles as written here. Please trim this to the actual deployment flow. This differs fromcmd/ocp-build-data-enforcer/main.go.🤖 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 `@cmd/ocp-build-data-enforcer/README.md` around lines 54 - 67, The Deployment section contains inaccurate details that do not match the actual implementation of ocp-build-data-enforcer as defined in main.go. Rewrite the deployment bullets to accurately describe the tool's config-driven workflow, removing the misleading references to iterating over fixed openshift-4.21/images trees and directly editing Dockerfiles. Ensure the rewritten bullets reflect the actual deployment flow and purpose of the enforcer tool as implemented in the codebase.cmd/registry-replacer/README.md (1)
59-67:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winSeparate the optional PR flow from the main flow.
This deployment section mixes the default registry-replacement path with the optional
--ensure-correct-promotion-dockerfilebehavior, and the last bullet makes it sound like the tool edits the Dockerfile itself. In practice it rewrites ci-operator config from fetched Dockerfile content, with PR creation gated separately. Tighten this so operators don't infer the wrong action. This differs fromcmd/registry-replacer/main.go.🤖 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 `@cmd/registry-replacer/README.md` around lines 59 - 67, The Deployment section conflates the core registry-replacement behavior with the optional `--ensure-correct-promotion-dockerfile` behavior and PR creation flow. Restructure this section to clearly separate the mandatory registry-replacement logic (which finds ci-operator configs, downloads Dockerfiles, updates configs to replace registry references, and removes invalid/obsolete replacements) from the optional PR flow (which is gated by the `--ensure-correct-promotion-dockerfile` flag and handles pushing to forks and creating PRs via the GitHub API). Clarify that the tool rewrites ci-operator configs based on fetched Dockerfile content rather than directly editing the Dockerfile itself, ensuring the documentation aligns with the actual behavior in main.go.cmd/prow-job-dispatcher/README.md (1)
67-72:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winDrop the stale dispatcher description.
This block still describes the old "last seven days / least jobs wins" algorithm and conflicts with the updated dispatch logic above and in the flag table. Keeping both versions in the same README makes the scheduler behavior ambiguous.
♻️ Suggested cleanup
- * It starts off by figuring out how many runs of each Prow jobs we had in the last seven days by querying the Prometheus instance in Prow-monitoring stack. - * It groups all jobs from a Prow job file together and will always try to put all of them on the same cluster. - * If a job has config stating it must be on a specific cluster, that will always be respected. This could lead to a job with tests on different clusters. We should not have many of those cases. - * If all e2e jobs in a group run on the same cloud provider, it will only consider clusters on that cloud provider, if any. Otherwise, all build clusters are considered. - * It will then choose the cluster with the least number of jobs, based on the Prometheus metrics and the already dispatched jobs.🤖 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 `@cmd/prow-job-dispatcher/README.md` around lines 67 - 72, The README contains a stale description of the dispatcher algorithm that references the old "last seven days / least jobs wins" approach and conflicts with the updated dispatch logic described elsewhere in the document. Remove the entire stale block that begins with "It starts off by figuring out how many runs of each Prow jobs we had in the last seven days" through "based on the Prometheus metrics and the already dispatched jobs." This will eliminate the ambiguity caused by having two conflicting versions of the scheduler behavior in the same README.cmd/job-run-aggregator/README.md (1)
109-117:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRemove the stale
create-tablesexample.
create-tablesis not one of the documented subcommands here, so this snippet will fail as written. It also duplicates thecreate-releasesexample above it.🤖 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 `@cmd/job-run-aggregator/README.md` around lines 109 - 117, Remove the final stale example from the README.md file that uses the create-tables subcommand (the block starting with the comment "This will create the Jobs table:"). This example duplicates the create-releases example shown immediately before it and references a subcommand that is not documented or supported, which will cause it to fail when executed. Delete both the comment line and the associated dlv exec command line that follows it.cmd/image-graph-generator/README.md (1)
79-89:⚠️ Potential issue | 🟠 Major | ⚡ Quick winRegenerate the usage snippet.
This block still lists
-ci-operator-configs-path/-image-mirroring-path, butcmd/image-graph-generator/main.goonly accepts--release-repoand--graphql-endpoint-address. As written, copying the example will fail immediately.🤖 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 `@cmd/image-graph-generator/README.md` around lines 79 - 89, The usage documentation snippet in the README shows command-line flags that no longer match the actual implementation in main.go. Update the usage block to reflect the current flags accepted by the image-graph-generator tool, removing the obsolete -ci-operator-configs-path and -image-mirroring-path flags and replacing them with the actual flags currently implemented (--release-repo and --graphql-endpoint-address) to ensure the documentation accurately represents what users will encounter when running the command.cmd/slack-bot/README.md (1)
70-77:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRestore the
hack/prefix in the sample command.The command currently omits the directory named in the prose, so readers will hit a missing-file error if they copy it verbatim.
🛠️ Suggested fix
-Run the `hack/local-slack-bot.sh` script like so: `RELEASE_REPO_DIR=<your openshift/release repo dir> bash local-slack-bot.sh` +Run the `hack/local-slack-bot.sh` script like so: `RELEASE_REPO_DIR=<your openshift/release repo dir> bash hack/local-slack-bot.sh`🤖 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 `@cmd/slack-bot/README.md` around lines 70 - 77, The command example in the Local testing section is missing the directory prefix for the script path. Update the bash command that runs the local-slack-bot.sh script to include the hack/ directory prefix before the script name so that readers following the instructions verbatim will correctly reference the script location at hack/local-slack-bot.sh.cmd/repo-init/README.md (1)
164-176:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix the local testing command path.
The prose points to
hack/local-repo-init-ui.sh, but the sample commands omithack/, so the copy-paste example fails from the repo root.🛠️ Suggested fix
-The easiest way to run the API/UI locally is to execute the `/hack/local-repo-init-ui.sh` script, like this: +The easiest way to run the API/UI locally is to execute the `hack/local-repo-init-ui.sh` script, like this: ```shell -repo-init --mode=cli --release-repo=/path/to/release/repo +./hack/local-repo-init-ui.sh start@@
-./local-repo-init-ui.sh stop
+./hack/local-repo-init-ui.sh stop</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@cmd/repo-init/README.mdaround lines 164 - 176, The shell command examples
in the README.md file for running local-repo-init-ui.sh are missing the
directory path prefix. Both the start and stop command examples currently show
./local-repo-init-ui.sh but should include the full relative path as
./hack/local-repo-init-ui.sh to match the prose description and allow the
copy-paste examples to work correctly from the repository root. Update both
command instances to include the hack/ directory prefix so users can
successfully execute them without encountering a file not found error.</details> <!-- cr-comment:v1:7c51526aea6d6f0492a9b906 --> </blockquote></details> </blockquote></details>🧹 Nitpick comments (7)
cmd/cluster-init/README.md (1)
98-110: ⚡ Quick winRemove the legacy usage block.
The trailing Create/Update/Create PR section duplicates the new lifecycle docs and reintroduces flags that are not covered above. Please fold the surviving examples into the flag tables or drop this block so the README has one source of truth.
🤖 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 `@cmd/cluster-init/README.md` around lines 98 - 110, Remove the legacy usage documentation block containing the "## Create", "## Update", and "## Create PR" sections as these duplicate the lifecycle documentation covered elsewhere in the README and reintroduce flags like --release-repo, --cluster-name, --update, --create-pr, --github-token-path, and --self-approve that should be documented in a single location. Either consolidate these examples into the flag reference tables if they provide unique value, or delete the entire block to establish a single source of truth for the tool's usage documentation.cmd/blocking-issue-creator/README.md (2)
56-85: ⚡ Quick winRemove the stale legacy sections.
The older “What it does / Why it exists / How it works / How is it deployed” block repeats the structured docs above and makes the README look like it has two canonical descriptions. Drop it unless it adds information that is missing from the new sections.
🤖 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 `@cmd/blocking-issue-creator/README.md` around lines 56 - 85, The README contains duplicate sections "What it does", "Why it exists", "How it works", and "How is it deployed" that repeat information already covered in the structured documentation above. Remove these four legacy section headers and their content from the README, unless the information they contain is unique and not already present in the structured sections above. If all the content is already covered, simply delete the entire legacy block to avoid redundancy and maintain a single canonical description.
18-19: ⚡ Quick winVerify the rate-limit numbers.
The flow says 5 seconds between repos to stay within 30 requests/minute, but the deployment note says 300 requests/minute burst/sustained. Please confirm which limit is real and keep one set of numbers in the README.
Also applies to: 51-52
🤖 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 `@cmd/blocking-issue-creator/README.md` around lines 18 - 19, The README contains conflicting GitHub API rate limit numbers: one section mentions 30 requests/minute as the secondary rate limit while another section (also noted in the deployment notes) references 300 requests/minute for burst/sustained rate limits. Verify the correct GitHub API rate limit that applies to this tool's use case, then update both occurrences (the rate limiting description around line 18-19 and the deployment notes around line 51-52) to use consistent and accurate numbers throughout the documentation. Ensure all rate limit references align with the actual GitHub API limits being respected by the tool.cmd/check-gh-automation/README.md (1)
66-103: ⚡ Quick winMake the auth examples match the new flag table.
The legacy examples at the bottom still use a different GitHub auth shape than the table above. Please verify the current invocation and update or remove the examples so the README doesn’t document two competing modes.
🤖 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 `@cmd/check-gh-automation/README.md` around lines 66 - 103, The README examples for running check-gh-automation are using inconsistent GitHub authentication parameters compared to the flag table documented above. Review the flag table that defines the current authentication options, then update all command examples (including those in the "Pass Prow Config Options", "Determine Modified Repos from Candidate and JobSpec", and "Pass specific Repo(s) to check" sections) to consistently use the same GitHub authentication flags as specified in the flag table. Remove or update any legacy examples that document competing or outdated authentication modes to ensure the README presents a single, consistent invocation pattern.cmd/ci-images-mirror/README.md (1)
80-149: ⚡ Quick winTrim the old narrative below the new sections.
The legacy block after the deployment section repeats the workflow in a different voice and brings back the older “temporary” / two-tag explanation. Please remove or merge it so the README presents a single, consistent flow.
🤖 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 `@cmd/ci-images-mirror/README.md` around lines 80 - 149, The README contains redundant legacy narrative that repeats the workflow explanation in a different voice and contradicts the updated information that states the tool is no longer temporary. Identify and remove the legacy block of text that appears after the deployment section and reiterates the two-tag mirroring explanation and "temporary" language. Ensure the README maintains a single, consistent voice by keeping only the current narrative sections that describe the tool functionality, extensions, and operational procedures without duplication.cmd/promoted-image-governor/README.md (1)
56-107: ⚡ Quick winDelete the duplicated legacy sections.
The old “What it does / Why it exists / How it works / How is it deployed” material below the new structured doc repeats the same content and makes the README look like it has two canonical descriptions. Keep one version.
🤖 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 `@cmd/promoted-image-governor/README.md` around lines 56 - 107, The README contains duplicated sections with the same content described in "What it does", "Why it exists", "How it works", and "How is it deployed". Remove the legacy/old version of these sections (keeping only the newer, better-structured version) to eliminate redundancy and maintain a single canonical description of the promoted-image-governor tool's purpose, functionality, and deployment.cmd/github-ldap-user-group-creator/README.md (1)
76-110: ⚡ Quick winDrop the legacy README block below the new summary.
It repeats the same tool description with outdated terminology (
github-id-group,github-id, etc.), which makes the README self-contradictory. Keep a single source of truth in the new top section.🤖 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 `@cmd/github-ldap-user-group-creator/README.md` around lines 76 - 110, The README contains duplicate documentation with outdated terminology that contradicts the newly added summary section. Remove the legacy README block that appears after the "How is it deployed" section, which repeats the tool description using outdated terms such as "github-id-group" and "github-id". Keep only the new comprehensive summary section ("What it does", "Why it exists", "How it works", "Deleting users", and "How is it deployed") to maintain a single source of truth in the documentation.🤖 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 `@cmd/auto-config-brancher/README.md`: - Line 22: The README documents a --rebalancer-cron flag and its behavior (lines 22 and 48), but this flag is not implemented anywhere in the codebase. Either remove all references to the --rebalancer-cron flag and the optional rebalancer step from the README documentation, or implement the feature by adding the flag definition to FutureOptions in main.go and adding the logic to check if the current time is within +/-1 hour of the cron schedule and prepend rebalancer as step 0 when appropriate. In `@cmd/backport-verifier/README.md`: - Around line 37-48: In the "On `/validate-backports` command" section, replace the abbreviated label name `unvalidated` with the fully qualified label name `backports/unvalidated-commits` in the text describing which label gets applied when the repo has no upstream configured. This ensures consistency with the complete label names shown in the Labels table below. In `@cmd/bugzilla-backporter/README.md`: - Line 20: The README.md documentation on line 20 lists the Prometheus metric prefix as `bugzillabackporter`, but the actual implementation in main.go exposes metrics under the prefix `ci-operator-bugzilla-backporter`. Update the README.md file to replace `bugzillabackporter` with the correct metric prefix `ci-operator-bugzilla-backporter` to ensure the documentation accurately reflects what is implemented and prevents confusion when setting up dashboards or alerts. In `@cmd/ci-operator/README.md`: - Around line 18-24: The namespace handling documentation describes a fixed pattern that does not match the actual contract. Update the overview section describing namespace handling to clarify that the namespace default comes from JOB_SPEC and that {id} substitution only applies when the --namespace flag explicitly includes it, rather than stating it always uses ci-op-{hash}. Additionally, update the corresponding flag table documentation to reflect this conditional behavior so the README accurately documents when each namespace pattern is used. In `@cmd/config-change-trigger/README.md`: - Around line 12-15: In the README.md file describing the Base version configuration, locate the text that currently describes `baseSHA^1` as "the merge base" in the parenthetical explanation. Reword this text to accurately describe `baseSHA^1` as the parent commit of the base SHA rather than the merge base, making it clear that `baseSHA^1` refers to the parent commit using language like "the parent commit of the base SHA (`baseSHA^1`)". In `@cmd/determinize-peribolos/README.md`: - Around line 24-28: Add blank lines around the flags table to comply with markdownlint requirements. Insert a blank line before the "## Flags" header to separate it from preceding content, and insert another blank line after the table's last row to separate it from any following content. This ensures proper markdown formatting with appropriate whitespace around structured elements. In `@cmd/determinize-prow-config/README.md`: - Around line 36-56: Add a language tag to the code fence displaying the sharded directory structure by specifying a language identifier (such as yaml or text) immediately after the opening triple backticks. Additionally, add blank lines before the Flags section header and around the flags table to provide proper visual separation between different content blocks in the markdown document. In `@cmd/dptp-controller-manager/README.md`: - Around line 34-38: The annotation key constant TTLAnnotationKey in the serviceaccount_secret_refresher controller contains a spelling error: `serviaccount` should be `serviceaccount`. Locate the TTLAnnotationKey constant definition in pkg/controller/serviceaccount_secret_refresher/serviceaccount_secret_refresher.go and correct the typo from `serviaccount-secret-rotator.openshift.io/delete-after` to `serviceaccount-secret-rotator.openshift.io/delete-after`. Then search the entire codebase for all usages of TTLAnnotationKey and any hardcoded references to the misspelled annotation key to ensure consistency throughout the implementation. In `@cmd/generate-registry-metadata/README.md`: - Around line 41-45: The Flags section table is missing required blank lines for Markdownlint compliance. Add a blank line before the "## Flags" heading and another blank line after the table ends (after the row containing the registry flag and its description). This provides the necessary whitespace around the table structure that Markdownlint expects. In `@cmd/multi-arch-builder-controller/README.md`: - Around line 76-79: The Requirements section in the README lists `manifest-tool` binary as a required dependency, but the actual implementation uses `manifestpusher.PushImageWithManifest()` and `oc image mirror` instead (as shown in main.go). Remove the bullet point mentioning the manifest-tool binary from the Requirements section, keeping only the valid requirement about target registry credentials mounted on /.docker/config.json. In `@cmd/ocp-build-data-enforcer/README.md`: - Line 26: The README.md documentation at line 26 does not accurately reflect the actual behavior of processDockerfile. The current wording suggests that content.source.git.branch.target is evaluated unconditionally with a fallback to the repo default branch, but the actual implementation only uses content.source.git.branch.target when it starts with openshift-, otherwise falling back to the repo default branch. Update the branch-selection note to accurately describe this conditional logic and match the implementation in cmd/ocp-build-data-enforcer/main.go. In `@cmd/payload-testing-ui/README.md`: - Around line 39-50: The README documents that the --port flag defaults to 8080, but the deployment section states the service runs on port 8000, creating a contradiction. Either update the README's Deployment section to explicitly note that the deployment overrides the default port flag to 8000, or update the actual deployment configuration to use port 8080 (the documented default). Choose whichever approach aligns with the intended deployment configuration, but ensure the documentation accurately reflects the actual port being used. In `@cmd/qci-appci/README.md`: - Around line 40-53: The flags table in the README.md file is not properly separated from the surrounding content with blank lines, which causes Markdownlint validation to fail. Add a blank line after the "## Flags" heading and before the table begins with the column headers (Flag, Default, What it controls), and also add a blank line after the last table row to properly separate the table from any content that follows it. In `@cmd/result-aggregator/README.md`: - Around line 31-33: The Authentication section in the README.md file incorrectly describes the password file format as "CSV format, colon-delimited" when CSV actually refers to comma-separated values. Reword the description to remove the CSV reference and clearly state that each line contains username:password pairs in a colon-delimited format, without mentioning CSV, to avoid ambiguity about the actual file structure. In `@cmd/serviceaccount-secret-rotation-trigger/README.md`: - Around line 20-24: In the README.md file under the "Clear SA secret references" section, the current description incorrectly claims that the Kubernetes control plane will automatically re-create default token and image pull secrets. Revise this statement to accurately reflect that clearing the `secrets` and `imagePullSecrets` references only removes the references themselves, and that the tool actually triggers a refresher controller to handle the recreation of these secrets, rather than implying Kubernetes does this automatically. In `@cmd/slack-bot/README.md`: - Around line 37-54: The Flags table in the README.md file is missing blank line separation from the surrounding markdown headings, which violates markdownlint rules. Add a blank line after the "## Flags" heading and before the table begins, and add a blank line after the table ends (before any subsequent content). This ensures proper markdown formatting and keeps the documentation build clean. In `@cmd/sprint-automation/README.md`: - Around line 45-55: The Flags table in the README is missing blank lines for proper markdown formatting which causes markdownlint violations. Add a blank line between the "## Flags" heading and the table header row that starts with the pipe characters, and add another blank line after the last row of the table (the kubeconfig row) before any following content. This separation will ensure the table is properly formatted and the README passes linting. In `@cmd/sync-rover-groups/README.md`: - Around line 3-6: Update the "What" section in the README.md to clarify that the GitHub-to-Kerberos user mappings YAML file is only output when the --github-users-file flag is set. Modify the wording to indicate that one file is always emitted (the resolved group memberships), while the second file (user mappings) is optional and depends on whether the --github-users-file flag is provided. This ensures readers understand the actual default behavior of the sync-rover-groups tool. In `@cmd/testgrid-config-generator/README.md`: - Around line 56-65: Add blank lines around the flags table in the README.md to comply with markdown linting rules. Insert a blank line before the "## Flags" section header and another blank line after the last row of the table. This ensures proper whitespace separation between the table and surrounding content. In `@cmd/vault-subpath-proxy/README.md`: - Around line 4-46: The documentation has inconsistent terminology about the secret sync timing: the overview states "synchronously syncs the secret data" but the detailed flow section under "KV write validation and sync (RoundTripper)" explicitly states "After a successful write (2xx response), asynchronously syncs the secret data to all Kubernetes clusters". Update the overview section to use "asynchronously" instead of "synchronously" to match the detailed flow description and accurately reflect that Kubernetes sync occurs after the Vault write completes and returns a response, not during the request processing. --- Outside diff comments: In `@cmd/autoowners/README.md`: - Around line 106-107: The usage snippet for the `--self-approve` flag in the README.md incorrectly shows `-self-approve approved` with a positional argument, but the flags table documents it as a boolean flag without any arguments. Remove the `approved` positional value from the usage example at line 106-107 so that it correctly shows `-self-approve` as a standalone boolean flag, or regenerate the usage documentation from the actual CLI help output to ensure consistency with the flag's actual implementation. In `@cmd/branchingconfigmanagers/README.md`: - Around line 254-345: Remove the entire "Config Manager Contract" section from the README.md file, which includes all subsections from "## Config Manager Contract" through the end of the "Deploying New Config Managers" section. This section is incomplete and marked with NOTE and TODO comments that undermine the documentation. Delete all content related to the contract definition, product lifecycle data structure, requirements for config managers, and deployment instructions that follow the incomplete deployment note. In `@cmd/ci-secret-bootstrap/README.md`: - Around line 68-141: The "Args and config.yaml" section and the "Run" section of the README document the legacy Bitwarden/kubeconfig approach with outdated parameters like --bw-password-path, --bw-user, and context-based cluster targeting, which conflicts with the current Vault/GSM model described earlier in the documentation. Remove the entire section starting from "## Args and config.yaml" through the end of the "## Run" section (including the code example with the ci-secret-bootstrap command) to eliminate this documentation contradiction and provide a single, consistent contract for the tool's usage. In `@cmd/ci-secret-generator/README.md`: - Around line 72-125: Remove the legacy Bitwarden documentation and examples from the README file. Delete the YAML configuration examples that show Bitwarden attribute and password mappings (the sections demonstrating password as an attribute name and field configurations), and remove the Run section that shows the Bitwarden CLI usage with flags like --bw-password-path and --bw-user. Replace these removed sections with documentation that reflects the current behavior of uploading secrets to Vault and optionally GSM instead, ensuring the CLI flags and configuration examples match the actual tool functionality. In `@cmd/config-brancher/README.md`: - Around line 94-98: The "Bumping configuration" section in the README still references the `--bump` flag while the rest of the documentation uses `--bump-release`. Update this legacy section by replacing all instances of `--bump` with `--bump-release` to maintain consistency throughout the README, or alternatively consider removing or rewriting this section if the information is already adequately covered in the new summary/table using the correct flag name. In `@cmd/gsm-secret-sync/README.md`: - Around line 72-125: Remove the legacy Bitwarden usage block from the README that contains references to `--bw-password-path` and `--bw-user` flags, as it conflicts with the new GCP and Vault workflow documented in the current sections. Search the entire file for any mentions of Bitwarden-related configuration, flags, environment variables, or usage examples and delete them completely to ensure the README only documents the current GCP-based backend and doesn't advertise incompatible or deprecated functionality. In `@cmd/image-graph-generator/README.md`: - Around line 79-89: The usage documentation snippet in the README shows command-line flags that no longer match the actual implementation in main.go. Update the usage block to reflect the current flags accepted by the image-graph-generator tool, removing the obsolete -ci-operator-configs-path and -image-mirroring-path flags and replacing them with the actual flags currently implemented (--release-repo and --graphql-endpoint-address) to ensure the documentation accurately represents what users will encounter when running the command. In `@cmd/job-run-aggregator/README.md`: - Around line 109-117: Remove the final stale example from the README.md file that uses the create-tables subcommand (the block starting with the comment "This will create the Jobs table:"). This example duplicates the create-releases example shown immediately before it and references a subcommand that is not documented or supported, which will cause it to fail when executed. Delete both the comment line and the associated dlv exec command line that follows it. In `@cmd/ocp-build-data-enforcer/README.md`: - Around line 54-67: The Deployment section contains inaccurate details that do not match the actual implementation of ocp-build-data-enforcer as defined in main.go. Rewrite the deployment bullets to accurately describe the tool's config-driven workflow, removing the misleading references to iterating over fixed openshift-4.21/images trees and directly editing Dockerfiles. Ensure the rewritten bullets reflect the actual deployment flow and purpose of the enforcer tool as implemented in the codebase. In `@cmd/private-org-sync/README.md`: - Around line 121-200: The example commands in the README.md file use outdated CLI flags that do not match the current documentation. Update the first command example that currently uses --config-path and --git-dir flags to use --config-dir instead, making it consistent with the flags table documentation and the second example command which already uses the correct --config-dir flag. Ensure all example invocations reflect the current CLI interface. - Around line 76-97: The deployment notes section still describes outdated behavior regarding missing destination repositories and merge conflict handling. Update this section to reflect the current implementation by removing the statement that missing destinations are unconditionally ignored and instead reference the `--fail-on-missing-destination` flag mentioned in the error-handling section above. Similarly, update the merge conflict statement to align with the current error-handling behavior documented elsewhere in the README to ensure consistency and clarity for readers about the actual tool behavior. In `@cmd/prow-job-dispatcher/README.md`: - Around line 67-72: The README contains a stale description of the dispatcher algorithm that references the old "last seven days / least jobs wins" approach and conflicts with the updated dispatch logic described elsewhere in the document. Remove the entire stale block that begins with "It starts off by figuring out how many runs of each Prow jobs we had in the last seven days" through "based on the Prometheus metrics and the already dispatched jobs." This will eliminate the ambiguity caused by having two conflicting versions of the scheduler behavior in the same README. In `@cmd/registry-replacer/README.md`: - Around line 59-67: The Deployment section conflates the core registry-replacement behavior with the optional `--ensure-correct-promotion-dockerfile` behavior and PR creation flow. Restructure this section to clearly separate the mandatory registry-replacement logic (which finds ci-operator configs, downloads Dockerfiles, updates configs to replace registry references, and removes invalid/obsolete replacements) from the optional PR flow (which is gated by the `--ensure-correct-promotion-dockerfile` flag and handles pushing to forks and creating PRs via the GitHub API). Clarify that the tool rewrites ci-operator configs based on fetched Dockerfile content rather than directly editing the Dockerfile itself, ensuring the documentation aligns with the actual behavior in main.go. In `@cmd/repo-init/README.md`: - Around line 164-176: The shell command examples in the README.md file for running local-repo-init-ui.sh are missing the directory path prefix. Both the start and stop command examples currently show ./local-repo-init-ui.sh but should include the full relative path as ./hack/local-repo-init-ui.sh to match the prose description and allow the copy-paste examples to work correctly from the repository root. Update both command instances to include the hack/ directory prefix so users can successfully execute them without encountering a file not found error. In `@cmd/sippy-config-generator/README.md`: - Around line 65-97: Remove the legacy manual-run appendix section from the README that includes the Related, Example invocation, Commit the output, and Customization subsections. These sections duplicate information already covered in the newer spec-style sections of the documentation. Delete this entire block to improve the README's readability and reduce redundant guidance. In `@cmd/slack-bot/README.md`: - Around line 70-77: The command example in the Local testing section is missing the directory prefix for the script path. Update the bash command that runs the local-slack-bot.sh script to include the hack/ directory prefix before the script name so that readers following the instructions verbatim will correctly reference the script location at hack/local-slack-bot.sh. In `@cmd/testgrid-config-generator/README.md`: - Around line 75-132: The legacy appendix section starting with "Note: Go 1.13 is required." and continuing through the end of the diff repeats older manual-run guidance and conflicts with the new spec-style sections above it, creating mixed instructions for readers. Remove this entire legacy appendix section or completely rewrite it to eliminate the duplication and conflicts with the newer documentation structure. The section includes the Go 1.13 note, build instructions using the go build command, the manual run example with testgrid-config-generator flags, and verification steps that appear to duplicate guidance from earlier in the document. In `@cmd/vault-secret-collection-manager/README.md`: - Around line 98-139: Remove the outdated endpoint documentation in the Endpoints section of the README that describes PATCH /secretcollection/:name for changing secret collection members. This endpoint documentation is inconsistent with the authoritative API contract which uses PUT /secretcollection/:name/members instead. Delete the bullet point containing the PATCH endpoint description to eliminate the ambiguity and keep only the correct current endpoint in the documentation. --- Nitpick comments: In `@cmd/blocking-issue-creator/README.md`: - Around line 56-85: The README contains duplicate sections "What it does", "Why it exists", "How it works", and "How is it deployed" that repeat information already covered in the structured documentation above. Remove these four legacy section headers and their content from the README, unless the information they contain is unique and not already present in the structured sections above. If all the content is already covered, simply delete the entire legacy block to avoid redundancy and maintain a single canonical description. - Around line 18-19: The README contains conflicting GitHub API rate limit numbers: one section mentions 30 requests/minute as the secondary rate limit while another section (also noted in the deployment notes) references 300 requests/minute for burst/sustained rate limits. Verify the correct GitHub API rate limit that applies to this tool's use case, then update both occurrences (the rate limiting description around line 18-19 and the deployment notes around line 51-52) to use consistent and accurate numbers throughout the documentation. Ensure all rate limit references align with the actual GitHub API limits being respected by the tool. In `@cmd/check-gh-automation/README.md`: - Around line 66-103: The README examples for running check-gh-automation are using inconsistent GitHub authentication parameters compared to the flag table documented above. Review the flag table that defines the current authentication options, then update all command examples (including those in the "Pass Prow Config Options", "Determine Modified Repos from Candidate and JobSpec", and "Pass specific Repo(s) to check" sections) to consistently use the same GitHub authentication flags as specified in the flag table. Remove or update any legacy examples that document competing or outdated authentication modes to ensure the README presents a single, consistent invocation pattern. In `@cmd/ci-images-mirror/README.md`: - Around line 80-149: The README contains redundant legacy narrative that repeats the workflow explanation in a different voice and contradicts the updated information that states the tool is no longer temporary. Identify and remove the legacy block of text that appears after the deployment section and reiterates the two-tag mirroring explanation and "temporary" language. Ensure the README maintains a single, consistent voice by keeping only the current narrative sections that describe the tool functionality, extensions, and operational procedures without duplication. In `@cmd/cluster-init/README.md`: - Around line 98-110: Remove the legacy usage documentation block containing the "## Create", "## Update", and "## Create PR" sections as these duplicate the lifecycle documentation covered elsewhere in the README and reintroduce flags like --release-repo, --cluster-name, --update, --create-pr, --github-token-path, and --self-approve that should be documented in a single location. Either consolidate these examples into the flag reference tables if they provide unique value, or delete the entire block to establish a single source of truth for the tool's usage documentation. In `@cmd/github-ldap-user-group-creator/README.md`: - Around line 76-110: The README contains duplicate documentation with outdated terminology that contradicts the newly added summary section. Remove the legacy README block that appears after the "How is it deployed" section, which repeats the tool description using outdated terms such as "github-id-group" and "github-id". Keep only the new comprehensive summary section ("What it does", "Why it exists", "How it works", "Deleting users", and "How is it deployed") to maintain a single source of truth in the documentation. In `@cmd/promoted-image-governor/README.md`: - Around line 56-107: The README contains duplicated sections with the same content described in "What it does", "Why it exists", "How it works", and "How is it deployed". Remove the legacy/old version of these sections (keeping only the newer, better-structured version) to eliminate redundancy and maintain a single canonical description of the promoted-image-governor tool's purpose, functionality, and deployment.🪄 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: Repository YAML (base), Central YAML (inherited)
Review profile: CHILL
Plan: Enterprise
Run ID:
a3c6be60-f3e1-4080-9631-b907f56023ce📒 Files selected for processing (78)
cmd/auto-config-brancher/README.mdcmd/auto-peribolos-sync/README.mdcmd/auto-testgrid-generator/README.mdcmd/autoowners/README.mdcmd/autopublicizeconfig/README.mdcmd/backport-verifier/README.mdcmd/blocking-issue-creator/README.mdcmd/branchingconfigmanagers/README.mdcmd/bugzilla-backporter/README.mdcmd/check-cluster-profiles-config/README.mdcmd/check-gh-automation/README.mdcmd/ci-images-mirror/README.mdcmd/ci-operator-checkconfig/README.mdcmd/ci-operator-config-mirror/README.mdcmd/ci-operator-configresolver/README.mdcmd/ci-operator-prowgen/README.mdcmd/ci-operator-yaml-creator/README.mdcmd/ci-operator/README.mdcmd/ci-scheduling-webhook/README.mdcmd/ci-secret-bootstrap/README.mdcmd/ci-secret-generator/README.mdcmd/cluster-display/README.mdcmd/cluster-init/README.mdcmd/clusterimageset-updater/README.mdcmd/config-brancher/README.mdcmd/config-change-trigger/README.mdcmd/config-shard-validator/README.mdcmd/cvp-trigger/README.mdcmd/determinize-ci-operator/README.mdcmd/determinize-peribolos/README.mdcmd/determinize-prow-config/README.mdcmd/docgen/README.mdcmd/dptp-controller-manager/README.mdcmd/dptp-pools-cm/README.mdcmd/entrypoint-wrapper/README.mdcmd/generate-registry-metadata/README.mdcmd/github-ldap-user-group-creator/README.mdcmd/gpu-scheduling-webhook/README.mdcmd/gsm-secret-sync/README.mdcmd/helpdesk-faq/README.mdcmd/image-graph-generator/README.mdcmd/job-run-aggregator/README.mdcmd/job-trigger-controller-manager/README.mdcmd/ldap-users-from-github-owners-files/README.mdcmd/lensserver/README.mdcmd/multi-arch-builder-controller/README.mdcmd/multi-pr-prow-plugin/README.mdcmd/ocp-build-data-enforcer/README.mdcmd/payload-testing-prow-plugin/README.mdcmd/payload-testing-ui/README.mdcmd/pipeline-controller/README.mdcmd/pj-rehearse/README.mdcmd/pod-scaler/README.mdcmd/pr-reminder/README.mdcmd/prcreator/README.mdcmd/private-org-peribolos-sync/README.mdcmd/private-org-sync/README.mdcmd/private-prow-configs-mirror/README.mdcmd/promoted-image-governor/README.mdcmd/prow-job-dispatcher/README.mdcmd/publicize/README.mdcmd/qci-appci/README.mdcmd/rebalancer/README.mdcmd/registry-replacer/README.mdcmd/release/README.mdcmd/repo-brancher/README.mdcmd/repo-init/README.mdcmd/result-aggregator/README.mdcmd/retester/README.mdcmd/sanitize-prow-jobs/README.mdcmd/serviceaccount-secret-rotation-trigger/README.mdcmd/sippy-config-generator/README.mdcmd/slack-bot/README.mdcmd/sprint-automation/README.mdcmd/sync-rover-groups/README.mdcmd/testgrid-config-generator/README.mdcmd/vault-secret-collection-manager/README.mdcmd/vault-subpath-proxy/README.md🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
openshift/release(manual)openshift/ci-docs(manual)openshift/release-controller(manual)openshift/ci-chat-bot(manual)
| | 8 | `clusterimageset-updater` | Update Hive ClusterImageSet resources | | ||
| | 9 | `promoted-image-governor` | Validate image promotion configs (dry-run) | | ||
|
|
||
| If `--rebalancer-cron` is set and the current time is within +/-1 hour of the cron schedule, `rebalancer` is prepended as step 0. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n --hidden --glob '!**/vendor/**' '\b(rebalancer|--rebalancer-cron)\b' cmd/auto-config-brancher cmd/rebalancerRepository: openshift/ci-tools
Length of output: 867
🏁 Script executed:
#!/bin/bash
# Check main.go for rebalancer-cron flag definition and usage
cat cmd/auto-config-brancher/main.go | head -200Repository: openshift/ci-tools
Length of output: 6159
🏁 Script executed:
#!/bin/bash
# Search for rebalancer-cron in main.go
rg -n 'rebalancer-cron|rebalancer' cmd/auto-config-brancher/main.goRepository: openshift/ci-tools
Length of output: 44
🏁 Script executed:
#!/bin/bash
# Find FutureOptions definition
rg -n 'type FutureOptions|--rebalancer-cron' pkg/promotion/Repository: openshift/ci-tools
Length of output: 120
🏁 Script executed:
#!/bin/bash
# Read FutureOptions struct
sed -n '95,150p' pkg/promotion/promotion.goRepository: openshift/ci-tools
Length of output: 2034
🏁 Script executed:
#!/bin/bash
# List all files in cmd/auto-config-brancher
find cmd/auto-config-brancher -type f -name "*.go"Repository: openshift/ci-tools
Length of output: 133
🏁 Script executed:
#!/bin/bash
# Search main_test.go for rebalancer references
rg -n 'rebalancer' cmd/auto-config-brancher/main_test.goRepository: openshift/ci-tools
Length of output: 44
Remove or implement the --rebalancer-cron flag and step.
The README documents a --rebalancer-cron flag and optional rebalancer step (lines 22, 48), but neither exist in the implementation. The flag is not defined in FutureOptions or anywhere in main.go, and there is no logic to prepend a rebalancer step. Either remove these from the documentation or implement the feature.
🤖 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 `@cmd/auto-config-brancher/README.md` at line 22, The README documents a
--rebalancer-cron flag and its behavior (lines 22 and 48), but this flag is not
implemented anywhere in the codebase. Either remove all references to the
--rebalancer-cron flag and the optional rebalancer step from the README
documentation, or implement the feature by adding the flag definition to
FutureOptions in main.go and adding the logic to check if the current time is
within +/-1 hour of the cron schedule and prepend rebalancer as step 0 when
appropriate.
Comment on lines
+37
to
+48
| ### On `/validate-backports` command | ||
| Same flow as above, but if the repo has no upstream configured, posts a comment saying so and applies the `unvalidated` label. | ||
|
|
||
| ### Labels | ||
| Based on the validation result, the plugin ensures exactly one of two labels is present: | ||
|
|
||
| | Label | Meaning | | ||
| |---|---| | ||
| | `backports/validated-commits` | All commits reference merged upstream PRs and no errors occurred | | ||
| | `backports/unvalidated-commits` | At least one commit is invalid or encountered an error | | ||
|
|
||
| When one label is added, the other is removed. The validated label is only applied when there are zero invalid commits AND zero errors. |
There was a problem hiding this comment.
Use the full label name here.
unvalidated is ambiguous and does not match the fully qualified label names listed below. Spell out backports/unvalidated-commits so the workflow stays consistent.
🤖 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 `@cmd/backport-verifier/README.md` around lines 37 - 48, In the "On
`/validate-backports` command" section, replace the abbreviated label name
`unvalidated` with the fully qualified label name
`backports/unvalidated-commits` in the text describing which label gets applied
when the repo has no upstream configured. This ensures consistency with the
complete label names shown in the Labels table below.
| | `/bug` | Return bug details as JSON | | ||
| | `/help` | Help/debug endpoint | | ||
|
|
||
| 5. Exports Prometheus metrics under `bugzillabackporter` (request duration, response size). |
There was a problem hiding this comment.
Fix the metric prefix.
main.go exposes Prometheus metrics under ci-operator-bugzilla-backporter; bugzillabackporter is the wrong name here and will mislead anyone wiring dashboards or alerts from this README.
🤖 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 `@cmd/bugzilla-backporter/README.md` at line 20, The README.md documentation on
line 20 lists the Prometheus metric prefix as `bugzillabackporter`, but the
actual implementation in main.go exposes metrics under the prefix
`ci-operator-bugzilla-backporter`. Update the README.md file to replace
`bugzillabackporter` with the correct metric prefix
`ci-operator-bugzilla-backporter` to ensure the documentation accurately
reflects what is implemented and prevents confusion when setting up dashboards
or alerts.
Comment on lines
+18
to
+24
| Namespace name: `ci-op-{hash}` where hash = SHA256 of all inputs, base32-encoded, 5 bytes. | ||
|
|
||
| Steps: | ||
| 1. ProjectRequest creation with retry loop (waits for TerminatingPhase to clear if a stale namespace exists) | ||
| 2. RBAC readiness check: SelfSubjectAccessReview for "create rolebindings" (30 retries, 1s each) | ||
| 3. Annotations: `ci.openshift.io/idle-cleanup-duration-ttl` (default 1h), `ci.openshift.io/cleanup-duration-ttl` (default 72h) | ||
| 4. Heartbeat goroutine updates `ci.openshift.io/namespace-last-active` every 10 minutes |
There was a problem hiding this comment.
Namespace handling is documented too narrowly.
The tool does not always use ci-op-{hash}. The CLI default comes from JOB_SPEC, and {id} substitution only applies when --namespace includes it. Please update this overview and the flag table so the README matches the actual contract.
Also applies to: 81-81
🤖 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 `@cmd/ci-operator/README.md` around lines 18 - 24, The namespace handling
documentation describes a fixed pattern that does not match the actual contract.
Update the overview section describing namespace handling to clarify that the
namespace default comes from JOB_SPEC and that {id} substitution only applies
when the --namespace flag explicitly includes it, rather than stating it always
uses ci-op-{hash}. Additionally, update the corresponding flag table
documentation to reflect this conditional behavior so the README accurately
documents when each namespace pattern is used.
Comment on lines
+12
to
+15
| 2. **Load configurations**: Load two complete snapshots of all CI configuration from the openshift/release checkout: | ||
| - **PR version** (`prConfig`): the current working copy at `--candidate-path` (includes the PR's changes) | ||
| - **Base version** (`masterConfig`): the configuration as it existed at the base SHA (`baseSHA^1`, i.e., the merge base) | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
rg -n 'BaseSHA|JOB_SPEC|ResolveSpecFromEnv' .Repository: openshift/ci-tools
Length of output: 32343
Reword "merge base" to accurately describe baseSHA^1
The README incorrectly describes baseSHA^1 as "the merge base." It is actually the parent commit of BaseSHA. Update line 15 to clarify this, e.g., "the parent commit of the base SHA (baseSHA^1)" rather than claiming it is the merge base.
🤖 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 `@cmd/config-change-trigger/README.md` around lines 12 - 15, In the README.md
file describing the Base version configuration, locate the text that currently
describes `baseSHA^1` as "the merge base" in the parenthetical explanation.
Reword this text to accurately describe `baseSHA^1` as the parent commit of the
base SHA rather than the merge base, making it clear that `baseSHA^1` refers to
the parent commit using language like "the parent commit of the base SHA
(`baseSHA^1`)".
Comment on lines
+37
to
+54
| ## Flags | ||
| | Flag | Default | What it controls | | ||
| |---|---|---| | ||
| | `--port` | `8888` | HTTP server listen port | | ||
| | `--log-level` | `info` | Log output level | | ||
| | `--grace-period` | `180s` | Graceful shutdown duration | | ||
| | `--slack-token-path` | (required) | Path to file containing the Slack bot token | | ||
| | `--slack-signing-secret-path` | (required) | Path to file containing the Slack signing secret | | ||
| | `--keywords-config-path` | (empty) | Path to the keywords auto-response config file | | ||
| | `--helpdesk-alias` | `@dptp-helpdesk` | Alias for the helpdesk user(s) | | ||
| | `--forum-channel-id` | `CBN38N3MW` | Slack channel ID for `#forum-ocp-testplatform` | | ||
| | `--review-request-workflow-id` | `B06T46F374N` | Slack workflow ID for review requests | | ||
| | `--namespace` | `ci` | Kubernetes namespace for storing helpdesk FAQ ConfigMaps | | ||
| | `--require-workflows-in-forum` | `true` | Require use of Slack workflows in the forum channel | | ||
| | `--prow-config-path` | (Prow) | Path to Prow config (for job link enrichment) | | ||
| | `--prow-job-config-path` | (Prow) | Path to Prow job configs | | ||
| | `--jira-*` | (various) | Jira connection options for issue filing | | ||
|
|
There was a problem hiding this comment.
Separate the flags table from the surrounding headings.
Markdownlint is flagging this section because the table isn't surrounded by blank lines. Add spacing before and after the table so the docs build stays clean.
🛠️ Suggested fix
## Flags
+
| Flag | Default | What it controls |
|---|---|
| `--port` | `8888` | HTTP server listen port |
| `--log-level` | `info` | Log output level |
| `--grace-period` | `180s` | Graceful shutdown duration |
| `--slack-token-path` | (required) | Path to file containing the Slack bot token |
| `--slack-signing-secret-path` | (required) | Path to file containing the Slack signing secret |
| `--keywords-config-path` | (empty) | Path to the keywords auto-response config file |
| `--helpdesk-alias` | `@dptp-helpdesk` | Alias for the helpdesk user(s) |
| `--forum-channel-id` | `CBN38N3MW` | Slack channel ID for `#forum-ocp-testplatform` |
| `--review-request-workflow-id` | `B06T46F374N` | Slack workflow ID for review requests |
| `--namespace` | `ci` | Kubernetes namespace for storing helpdesk FAQ ConfigMaps |
| `--require-workflows-in-forum` | `true` | Require use of Slack workflows in the forum channel |
| `--prow-config-path` | (Prow) | Path to Prow config (for job link enrichment) |
| `--prow-job-config-path` | (Prow) | Path to Prow job configs |
| `--jira-*` | (various) | Jira connection options for issue filing |
+
## Key files📝 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
| ## Flags | |
| | Flag | Default | What it controls | | |
| |---|---|---| | |
| | `--port` | `8888` | HTTP server listen port | | |
| | `--log-level` | `info` | Log output level | | |
| | `--grace-period` | `180s` | Graceful shutdown duration | | |
| | `--slack-token-path` | (required) | Path to file containing the Slack bot token | | |
| | `--slack-signing-secret-path` | (required) | Path to file containing the Slack signing secret | | |
| | `--keywords-config-path` | (empty) | Path to the keywords auto-response config file | | |
| | `--helpdesk-alias` | `@dptp-helpdesk` | Alias for the helpdesk user(s) | | |
| | `--forum-channel-id` | `CBN38N3MW` | Slack channel ID for `#forum-ocp-testplatform` | | |
| | `--review-request-workflow-id` | `B06T46F374N` | Slack workflow ID for review requests | | |
| | `--namespace` | `ci` | Kubernetes namespace for storing helpdesk FAQ ConfigMaps | | |
| | `--require-workflows-in-forum` | `true` | Require use of Slack workflows in the forum channel | | |
| | `--prow-config-path` | (Prow) | Path to Prow config (for job link enrichment) | | |
| | `--prow-job-config-path` | (Prow) | Path to Prow job configs | | |
| | `--jira-*` | (various) | Jira connection options for issue filing | | |
| ## Flags | |
| | Flag | Default | What it controls | | |
| |---|---|---| | |
| | `--port` | `8888` | HTTP server listen port | | |
| | `--log-level` | `info` | Log output level | | |
| | `--grace-period` | `180s` | Graceful shutdown duration | | |
| | `--slack-token-path` | (required) | Path to file containing the Slack bot token | | |
| | `--slack-signing-secret-path` | (required) | Path to file containing the Slack signing secret | | |
| | `--keywords-config-path` | (empty) | Path to the keywords auto-response config file | | |
| | `--helpdesk-alias` | `@dptp-helpdesk` | Alias for the helpdesk user(s) | | |
| | `--forum-channel-id` | `CBN38N3MW` | Slack channel ID for `#forum-ocp-testplatform` | | |
| | `--review-request-workflow-id` | `B06T46F374N` | Slack workflow ID for review requests | | |
| | `--namespace` | `ci` | Kubernetes namespace for storing helpdesk FAQ ConfigMaps | | |
| | `--require-workflows-in-forum` | `true` | Require use of Slack workflows in the forum channel | | |
| | `--prow-config-path` | (Prow) | Path to Prow config (for job link enrichment) | | |
| | `--prow-job-config-path` | (Prow) | Path to Prow job configs | | |
| | `--jira-*` | (various) | Jira connection options for issue filing | | |
| ## Key files |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 38-38: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 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 `@cmd/slack-bot/README.md` around lines 37 - 54, The Flags table in the
README.md file is missing blank line separation from the surrounding markdown
headings, which violates markdownlint rules. Add a blank line after the "##
Flags" heading and before the table begins, and add a blank line after the table
ends (before any subsequent content). This ensures proper markdown formatting
and keeps the documentation build clean.
Source: Linters/SAST tools
Comment on lines
+45
to
+55
| ## Flags | ||
| | Flag | Default | What it controls | | ||
| |---|---|---| | ||
| | `--log-level` | `info` | Log output level | | ||
| | `--slack-token-path` | (required) | Path to the Slack bot token file | | ||
| | `--week-start` | `false` | Enable Monday-only activities (next week roles, triage handover) | | ||
| | `--enable-build02-upgrade-notification` | `false` | Check if build02 needs upgrading to match build01 | | ||
| | `--jira-*` | (various) | Jira connection options | | ||
| | `--pagerduty-*` | (various) | PagerDuty API options | | ||
| | `--kubeconfig` | (various) | Kubeconfig for build01 and build02 clusters | | ||
|
|
There was a problem hiding this comment.
Separate the flags table from the surrounding headings.
Markdownlint is already flagging this section; add a blank line before and after the table to keep the README lint-clean.
🛠️ Suggested fix
## Flags
+
| Flag | Default | What it controls |
|---|---|
| `--log-level` | `info` | Log output level |
| `--slack-token-path` | (required) | Path to the Slack bot token file |
| `--week-start` | `false` | Enable Monday-only activities (next week roles, triage handover) |
| `--enable-build02-upgrade-notification` | `false` | Check if build02 needs upgrading to match build01 |
| `--jira-*` | (various) | Jira connection options |
| `--pagerduty-*` | (various) | PagerDuty API options |
| `--kubeconfig` | (various) | Kubeconfig for build01 and build02 clusters |
+
## Key files📝 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
| ## Flags | |
| | Flag | Default | What it controls | | |
| |---|---|---| | |
| | `--log-level` | `info` | Log output level | | |
| | `--slack-token-path` | (required) | Path to the Slack bot token file | | |
| | `--week-start` | `false` | Enable Monday-only activities (next week roles, triage handover) | | |
| | `--enable-build02-upgrade-notification` | `false` | Check if build02 needs upgrading to match build01 | | |
| | `--jira-*` | (various) | Jira connection options | | |
| | `--pagerduty-*` | (various) | PagerDuty API options | | |
| | `--kubeconfig` | (various) | Kubeconfig for build01 and build02 clusters | | |
| ## Flags | |
| | Flag | Default | What it controls | | |
| |---|---|---| | |
| | `--log-level` | `info` | Log output level | | |
| | `--slack-token-path` | (required) | Path to the Slack bot token file | | |
| | `--week-start` | `false` | Enable Monday-only activities (next week roles, triage handover) | | |
| | `--enable-build02-upgrade-notification` | `false` | Check if build02 needs upgrading to match build01 | | |
| | `--jira-*` | (various) | Jira connection options | | |
| | `--pagerduty-*` | (various) | PagerDuty API options | | |
| | `--kubeconfig` | (various) | Kubeconfig for build01 and build02 clusters | | |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 46-46: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 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 `@cmd/sprint-automation/README.md` around lines 45 - 55, The Flags table in the
README is missing blank lines for proper markdown formatting which causes
markdownlint violations. Add a blank line between the "## Flags" heading and the
table header row that starts with the pipe characters, and add another blank
line after the last row of the table (the kubeconfig row) before any following
content. This separation will ensure the table is properly formatted and the
README passes linting.
Source: Linters/SAST tools
Comment on lines
+3
to
+6
| ## What | ||
| Resolves Red Hat LDAP Rover group memberships by scanning Kubernetes manifest directories for group references and querying the corporate LDAP server to resolve each group's member list. Outputs two YAML files consumed by `github-ldap-user-group-creator`: one with resolved group memberships and one with GitHub-to-Kerberos user mappings. | ||
|
|
||
| This is the first half of the group sync pipeline. It runs on the Red Hat intranet (PSI cluster) because it needs direct LDAP access. |
There was a problem hiding this comment.
Mark the GitHub users file as optional.
This summary says the tool always emits two YAML files, but --github-users-file is only written when that flag is set. Tightening the wording avoids misleading readers about the default output.
🛠️ Suggested fix
-Outputs two YAML files consumed by `github-ldap-user-group-creator`: one with resolved group memberships and one with GitHub-to-Kerberos user mappings.
+Outputs a resolved groups YAML file consumed by `github-ldap-user-group-creator`, and optionally a GitHub-to-Kerberos user mapping file when `--github-users-file` is set.📝 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
| ## What | |
| Resolves Red Hat LDAP Rover group memberships by scanning Kubernetes manifest directories for group references and querying the corporate LDAP server to resolve each group's member list. Outputs two YAML files consumed by `github-ldap-user-group-creator`: one with resolved group memberships and one with GitHub-to-Kerberos user mappings. | |
| This is the first half of the group sync pipeline. It runs on the Red Hat intranet (PSI cluster) because it needs direct LDAP access. | |
| ## What | |
| Resolves Red Hat LDAP Rover group memberships by scanning Kubernetes manifest directories for group references and querying the corporate LDAP server to resolve each group's member list. Outputs a resolved groups YAML file consumed by `github-ldap-user-group-creator`, and optionally a GitHub-to-Kerberos user mapping file when `--github-users-file` is set. | |
| This is the first half of the group sync pipeline. It runs on the Red Hat intranet (PSI cluster) because it needs direct LDAP access. |
🤖 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 `@cmd/sync-rover-groups/README.md` around lines 3 - 6, Update the "What"
section in the README.md to clarify that the GitHub-to-Kerberos user mappings
YAML file is only output when the --github-users-file flag is set. Modify the
wording to indicate that one file is always emitted (the resolved group
memberships), while the second file (user mappings) is optional and depends on
whether the --github-users-file flag is provided. This ensures readers
understand the actual default behavior of the sync-rover-groups tool.
Comment on lines
+56
to
+65
| ## Flags | ||
| | Flag | Default | What it controls | | ||
| |---|---|---| | ||
| | `--prow-jobs-dir` | (required unless `--validate`) | Path to Prow job config directory (`ci-operator/jobs` in openshift/release) | | ||
| | `--release-config` | (required) | Path to release controller configuration directory | | ||
| | `--testgrid-config` | (required unless `--validate`) | Path to TestGrid configuration output directory | | ||
| | `--allow-list` | (required) | Path to YAML file with job classification overrides | | ||
| | `--validate` | false | Only validate the allow-list, skip generation | | ||
| | `--google-storage-bucket` | `test-platform-results` | GCS bucket for test artifact links | | ||
|
|
There was a problem hiding this comment.
Add blank lines around the flags table.
Markdownlint will flag this table as missing surrounding whitespace.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 57-57: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 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 `@cmd/testgrid-config-generator/README.md` around lines 56 - 65, Add blank
lines around the flags table in the README.md to comply with markdown linting
rules. Insert a blank line before the "## Flags" section header and another
blank line after the last row of the table. This ensures proper whitespace
separation between the table and surrounding content.
Source: Linters/SAST tools
Comment on lines
+4
to
+46
| Reverse proxy for Vault that adds two capabilities the upstream Vault server lacks: | ||
| 1. **Subpath discovery:** when a user gets a 403 on a KV metadata list request, the proxy inspects their effective ACL permissions and injects accessible subpaths into the response, making folders visible in the Vault UI even without list permission on the parent. | ||
| 2. **KV write validation and secret sync:** intercepts KV write requests (PUT/POST/PATCH/DELETE), validates secret keys against Kubernetes naming rules, checks for conflicting keys across secrets targeting the same namespace/name, and synchronously syncs the secret data to Kubernetes clusters. | ||
|
|
||
| ## How it works -- full flow | ||
|
|
||
| ### Subpath injection (ModifyResponse) | ||
| 1. The proxy forwards all requests to the upstream Vault server. | ||
| 2. On the response path, if the response is a **403** to a **GET** request on a KV **metadata** path with `?list=true`: | ||
| - Reads and buffers the original response body. | ||
| - Checks if Vault already returned data (non-empty `keys` array). If so, does nothing. | ||
| - Extracts the user's Vault token from the `X-Vault-Token` header. | ||
| - Calls Vault's `/v1/sys/internal/ui/resultant-acl` API with the user's token to get their effective permissions. | ||
| - Scans the glob paths in the ACL result for paths that: | ||
| - Start with the requested folder's metadata prefix | ||
| - End with `/` (indicating a folder) | ||
| - Have the `list` capability | ||
| - If any matching folders are found, replaces the 403 response with a 200 containing the discovered subpaths as `keys`. | ||
|
|
||
| ### KV write validation and sync (RoundTripper) | ||
| For PUT/POST/PATCH requests to KV paths: | ||
|
|
||
| 1. **Key validation.** Reads and parses the request body as `{"data": {...}}`. For each key: | ||
| - `secretsync/target-namespace`: validates each comma-separated namespace is a valid DNS-1123 label. | ||
| - `secretsync/target-name`: validates as DNS-1123 label. | ||
| - `secretsync/target-cluster`: skipped (no validation needed). | ||
| - All other keys: must match `^[a-zA-Z0-9\.\-_]+$`. | ||
| - Validates the secret can be used in a CI step (`ci_validation.ValidateSecretInStep`). | ||
|
|
||
| 2. **Conflict detection.** If a privileged Vault client is configured: | ||
| - On first request, populates a key cache by listing all KV entries recursively and building a map of `{namespace, name} -> set of keys` and `vaultPath -> [{namespace, name, key}]`. | ||
| - For each key in the request, checks if the same key is already claimed by a *different* Vault secret targeting the same Kubernetes namespace/name. This prevents two Vault entries from writing conflicting keys to the same Kubernetes Secret. | ||
| - The cache is updated after successful writes and deletes. | ||
|
|
||
| 3. **Upstream forwarding.** If validation passes, forwards the request to Vault. | ||
|
|
||
| 4. **Secret sync.** After a successful write (2xx response), asynchronously syncs the secret data to all Kubernetes clusters: | ||
| - Iterates all configured Kubernetes clients. | ||
| - For each cluster that the secret targets (per `secretsync/target-cluster`), and for each target namespace (comma-separated): | ||
| - Creates or updates a Kubernetes Secret with the data keys from the Vault entry. | ||
| - Uses `controllerutil.CreateOrUpdate` with retry on conflict. | ||
| - Sync has a 5-minute timeout per operation. | ||
|
|
There was a problem hiding this comment.
Make the sync timing wording consistent.
The overview says secret sync is synchronous, but the detailed flow says writes return first and Kubernetes sync happens asynchronously after a 2xx response. Pick one phrasing so readers don't infer the wrong latency/failure semantics.
🤖 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 `@cmd/vault-subpath-proxy/README.md` around lines 4 - 46, The documentation has
inconsistent terminology about the secret sync timing: the overview states
"synchronously syncs the secret data" but the detailed flow section under "KV
write validation and sync (RoundTripper)" explicitly states "After a successful
write (2xx response), asynchronously syncs the secret data to all Kubernetes
clusters". Update the overview section to use "asynchronously" instead of
"synchronously" to match the detailed flow description and accurately reflect
that Kubernetes sync occurs after the Vault write completes and returns a
response, not during the request processing.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
cmd/directories with standardized documentation (what, how it works, flags, key files, deployment)openshift/releasemanifests and corrected where inaccurate🤖 Generated with Claude Code
Standardized README Documentation Across OpenShift CI Command-Line Tools
This pull request adds comprehensive, standardized README.md documentation across all 79 command-line tools and services in the OpenShift CI infrastructure's
cmd/directories.What Changed
Documentation standardization: Every tool now has a consistent
README.mdwith:Affected tools span the entire CI infrastructure, including:
ci-operator,ci-operator-configresolverauto-config-brancher,config-brancher,branchingconfigmanagers,ci-operator-prowgenprow-job-dispatcher,job-trigger-controller-manager,multi-pr-prow-pluginretester,rebalancer,repo-brancher,cluster-init,payload-testing-prow-pluginci-scheduling-webhook,vault-secret-collection-manager,dptp-controller-managerKey Improvements
Accuracy verification: Cross-referenced deployment information against
openshift/releasemanifests, identifying and correcting 8 inaccuracies related to:Consistent structure: Removed empty placeholder sections (like
## Ownership) and standardized heading levels for cleaner, more navigable documentation.Practical value for operators: Provides authoritative, point-of-reference documentation for anyone deploying, troubleshooting, or extending OpenShift CI infrastructure. All tools now follow the same documentation pattern, reducing time to understand tool usage and deployment.
This is a documentation-only change with no impact on tool functionality or behavior.