From 1b8069c9d5060ab94eef0f2edeeb156b90e0db17 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Moritz=20Schmitz=20von=20H=C3=BClst?=
 <mschmitzvonhuelst@gmail.com>
Date: Mon, 29 Jun 2026 01:28:59 +0200
Subject: [PATCH 1/2] feat: add CI workflow to auto-update CLI docs (#31)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Moritz Schmitz von Hülst <mschmitzvonhuelst@gmail.com>
---
 .github/workflows/update-docs.yml | 83 +++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 .github/workflows/update-docs.yml

diff --git a/.github/workflows/update-docs.yml b/.github/workflows/update-docs.yml
new file mode 100644
index 0000000..61a0d2c
--- /dev/null
+++ b/.github/workflows/update-docs.yml
@@ -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
+    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"
+          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
+
+      - 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

From 8a487fe90f925db57633b424ed2b8d147a5325dc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Moritz=20Schmitz=20von=20H=C3=BClst?=
 <mschmitzvonhuelst@gmail.com>
Date: Wed, 1 Jul 2026 01:20:56 +0200
Subject: [PATCH 2/2] fix: address review feedback on update-docs workflow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Remove main branch trigger (docs already updated via ci workflow)
- Add concurrency group to prevent overlapping runs
- Strip patch version from directory name (v2.4.1 -> v2.4)
- Use git status --porcelain to detect untracked new files

Signed-off-by: Moritz Schmitz von Hülst <mschmitzvonhuelst@gmail.com>
---
 .github/workflows/update-docs.yml | 17 +++++++----------
 1 file changed, 7 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/update-docs.yml b/.github/workflows/update-docs.yml
index 61a0d2c..b69c977 100644
--- a/.github/workflows/update-docs.yml
+++ b/.github/workflows/update-docs.yml
@@ -2,8 +2,6 @@ name: Update CLI Docs
 
 on:
   push:
-    branches:
-      - main
     tags:
       - 'v*'
 
@@ -12,6 +10,9 @@ permissions:
 
 jobs:
   update-docs:
+    concurrency:
+      group: update-cli-docs
+      cancel-in-progress: true
     permissions:
       contents: write
       pull-requests: write
@@ -49,20 +50,16 @@ jobs:
       - 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"
-          else
-            echo "dir=content/cli/master" >> "$GITHUB_OUTPUT"
-          fi
+          VERSION="${GITHUB_REF#refs/tags/}"
+          MINOR_VERSION="${VERSION%.*}"
+          echo "dir=content/cli/${MINOR_VERSION#v}" >> "$GITHUB_OUTPUT"
 
       - 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