Skip to content

feat: add CI workflow to auto-update CLI docs (#31) #167

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Open
boxcee-interview wants to merge 1 commit into
base: main
Choose a base branch
from
+83 −0
Open

feat: add CI workflow to auto-update CLI docs (#31) #167

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

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 83 additions & 0 deletions .github/workflows/update-docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
name: Update CLI Docs

on:
push:
branches:
- main
tags:
- 'v*'

permissions:
contents: read

jobs:
update-docs:
permissions:
contents: write
pull-requests: write
runs-on: ubuntu-24.04
Comment on lines +14 to +18

@coderabbitai coderabbitai Bot Jun 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🗄️ 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: write

Also 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.

steps:
- name: Checkout
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

- name: Install Nix
uses: cachix/install-nix-action@4e002c8ec80594ecd40e759629461e26c8abed15 # v31

- name: Setup Cachix
uses: cachix/cachix-action@3ba601ff5bbb07c7220846facfa2cd81eeee15a1 # v16
with:
name: crossplane
authToken: ${{ secrets.CACHIX_AUTH_TOKEN }}

- name: Build CLI
run: |
nix build .#crossplane --print-build-logs
cp result/bin/crossplane /tmp/crossplane

- name: Generate Docs
run: |
mkdir -p generated-docs
/tmp/crossplane generate-docs -o generated-docs/command-reference.md

- name: Checkout Docs
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
with:
repository: crossplane/docs
token: ${{ secrets.DOCS_WRITE_TOKEN }}
path: docs

- name: Determine Target Directory
id: target
run: |
if [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
VERSION="${GITHUB_REF#refs/tags/}"
DIR_NAME="${VERSION#v}"
echo "dir=content/cli/${DIR_NAME}" >> "$GITHUB_OUTPUT"
Comment on lines +53 to +55

@adamwg adamwg Jun 29, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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.

else
echo "dir=content/cli/master" >> "$GITHUB_OUTPUT"
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 ! git diff --quiet; then
echo "docs-changed=true" >> "$GITHUB_ENV"
fi
Comment on lines +60 to +67

@coderabbitai coderabbitai Bot Jun 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🗄️ 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.

Suggested change
- 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.


- name: Create Pull Request
if: env.docs-changed == 'true'
uses: peter-evans/create-pull-request@204220e584d39b97d07e8e00693fe658ea76b09d # v7
with:
path: docs
token: ${{ secrets.DOCS_WRITE_TOKEN }}
commit-message: "docs(cli): auto-update command reference"
title: "docs(cli): auto-update command reference for ${{ steps.target.outputs.dir }}"
body: |
Auto-generated CLI command reference update.

Generated from: `${{ github.sha }}`
Trigger: `${{ github.event_name }} ${{ github.ref }}`
branch: auto/update-cli-docs
delete-branch: true