feat: add CI workflow to auto-update CLI docs (#31)#167
feat: add CI workflow to auto-update CLI docs (#31)#167boxcee-interview wants to merge 1 commit into
Conversation
Signed-off-by: Moritz Schmitz von Hülst <mschmitzvonhuelst@gmail.com>
boxcee-interview
requested review from
a team,
jcogilvie and
tampakrap
as code owners
📝 WalkthroughWalkthroughA new GitHub Actions workflow ( ChangesAutomated CLI Docs Update Workflow
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 6✅ Passed checks (6 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/update-docs.yml:
- Around line 14-18: The update-docs workflow can have overlapping runs writing
to the shared auto/update-cli-docs branch, which can cause out-of-order docs
updates. Add workflow-level serialization in update-docs and/or make the PR
branch name unique per target directory before the branch is reused, so only one
run of the update-docs job can write at a time and the generated docs PR stays
current.
- Around line 60-67: The docs change detection in the Update Docs step misses
newly created untracked files, so first-time release docs can be skipped. Update
the gate in the Update Docs workflow to use a status check that includes
untracked files, or stage the generated docs before checking, so the
`docs-changed` flag is set when `command-reference.md` is newly added. Use the
`Update Docs` step and its `git diff --quiet` check as the location to adjust.
🪄 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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 9ba7c8c3-3946-4d7d-85f8-97b202caf5d1
📒 Files selected for processing (1)
.github/workflows/update-docs.yml
| update-docs: | ||
| permissions: | ||
| contents: write | ||
| pull-requests: write | ||
| runs-on: ubuntu-24.04 |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Serialize this workflow before reusing auto/update-cli-docs.
Appreciate the automation here. Because every main push and every release tag writes to the same branch at Line 82, overlapping runs can update that branch out of order and leave the docs PR pointing at older generated content. Could we add concurrency or derive the PR branch from the target directory so only one writer owns the branch at a time?
One simple hardening option
jobs:
update-docs:
+ concurrency:
+ group: update-cli-docs
+ cancel-in-progress: true
permissions:
contents: write
pull-requests: writeAlso applies to: 69-83
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/update-docs.yml around lines 14 - 18, The update-docs
workflow can have overlapping runs writing to the shared auto/update-cli-docs
branch, which can cause out-of-order docs updates. Add workflow-level
serialization in update-docs and/or make the PR branch name unique per target
directory before the branch is reused, so only one run of the update-docs job
can write at a time and the generated docs PR stays current.
| - name: Update Docs | ||
| run: | | ||
| mkdir -p docs/${{ steps.target.outputs.dir }} | ||
| cp generated-docs/command-reference.md docs/${{ steps.target.outputs.dir }}/command-reference.md | ||
| cd docs | ||
| if ! git diff --quiet; then | ||
| echo "docs-changed=true" >> "$GITHUB_ENV" | ||
| fi |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Handle untracked release docs when deciding whether to open a PR.
Thanks for wiring this up. On a first release for a new target directory, Line 63 creates an untracked command-reference.md, but Line 65 uses git diff --quiet, which ignores untracked files. In that case docs-changed never flips to true, so the workflow skips PR creation exactly when a new release doc needs to be added. Could we switch this gate to git status --porcelain (or stage intent-to-add) so new files count too?
Proposed fix
- name: Update Docs
run: |
mkdir -p docs/${{ steps.target.outputs.dir }}
cp generated-docs/command-reference.md docs/${{ steps.target.outputs.dir }}/command-reference.md
cd docs
- if ! git diff --quiet; then
+ if [[ -n "$(git status --porcelain --untracked-files=all)" ]]; then
echo "docs-changed=true" >> "$GITHUB_ENV"
fi📝 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.
| - name: Update Docs | |
| run: | | |
| mkdir -p docs/${{ steps.target.outputs.dir }} | |
| cp generated-docs/command-reference.md docs/${{ steps.target.outputs.dir }}/command-reference.md | |
| cd docs | |
| if ! git diff --quiet; then | |
| echo "docs-changed=true" >> "$GITHUB_ENV" | |
| fi | |
| - name: Update Docs | |
| run: | | |
| mkdir -p docs/${{ steps.target.outputs.dir }} | |
| cp generated-docs/command-reference.md docs/${{ steps.target.outputs.dir }}/command-reference.md | |
| cd docs | |
| if [[ -n "$(git status --porcelain --untracked-files=all)" ]]; then | |
| echo "docs-changed=true" >> "$GITHUB_ENV" | |
| fi |
🧰 Tools
🪛 zizmor (1.26.1)
[info] 62-62: code injection via template expansion (template-injection): may expand into attacker-controllable code
(template-injection)
[info] 63-63: code injection via template expansion (template-injection): may expand into attacker-controllable code
(template-injection)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/update-docs.yml around lines 60 - 67, The docs change
detection in the Update Docs step misses newly created untracked files, so
first-time release docs can be skipped. Update the gate in the Update Docs
workflow to use a status check that includes untracked files, or stage the
generated docs before checking, so the `docs-changed` flag is set when
`command-reference.md` is newly added. Use the `Update Docs` step and its `git
diff --quiet` check as the location to adjust.
adamwg
left a comment
adamwg
left a comment
There was a problem hiding this comment.
Thanks for taking a look at this!
We already have automated docs updates working on the main branch as part of the Validate Docs job in the ci workflow. No objection to centralizing the updates if we can have a single workflow handle both releases and main updates, but we shouldn't do it twice.
For releases, I think we shouldn't update docs until the release has been promoted to the stable channel. It might make sense to attach the docs update to the promote workflow.
| VERSION="${GITHUB_REF#refs/tags/}" | ||
| DIR_NAME="${VERSION#v}" | ||
| echo "dir=content/cli/${DIR_NAME}" >> "$GITHUB_OUTPUT" |
There was a problem hiding this comment.
Note that the docs are versioned per minor version, not for each patch. The tag will be (e.g.) v2.4.1, so this logic needs to strip the patch portion to make the directory name v2.4.
|
Addressed review feedback:
Regarding the promote workflow question: happy to discuss whether attaching the docs update to the promote workflow makes more sense. For now, keeping the tag-triggered workflow as a first pass. |
|
Addressed review feedback:
Regarding the promote workflow question: happy to discuss whether attaching the docs update to the promote workflow makes more sense. For now, keeping the tag-triggered workflow as a first pass. |
2 participants
Closes #31
Adds a GitHub Actions workflow that automatically updates CLI command reference documentation in the crossplane/docs repository.
Changes
.github/workflows/update-docs.ymlworkflow triggered on push to main and on release tagscrossplane generate-docs, then creates a PR to crossplane/docs viapeter-evans/create-pull-requestHow to Test
Requires a
DOCS_WRITE_TOKENsecret with write access to crossplane/docs repo. The workflow will create a PR to that repo when triggered on push to main or a new tag.