ci: Update the CLI reference documentation on every merge

[adamwg]

Description of your changes

The CLI documentation is versioned, and its "master" version should reflect what's currently in our main branch. Since our reference docs are auto-generated by the generate-docs command, this means we can automatically keep the "master" docs in sync with our main branch by updating them from CI.

Toward #31

I have:

• Read and followed Crossplane's contribution process.
• Run ./nix.sh flake check to ensure this PR is ready for review.
  - [ ] Added or updated unit tests.
  - [ ] Linked a PR or a docs tracking issue to document this change.
  - [ ] Added backport release-x.y labels to auto-backport this PR.

[adamwg]

I've tested this using my own fork of c/cli and c/docs:

• CI run that has docs updates and creates a PR: https://github.com/adamwg/crossplane-cli/actions/runs/27444696906 -> Update master CLI reference docs for cb27ed7 adamwg/docs#1
• CI run that does not change docs, and does not create a PR: https://github.com/adamwg/crossplane-cli/actions/runs/27445189664

[coderabbitai]

Warning

Review limit reached

@adamwg, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 25 minutes and 26 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 543c55f6-98d9-4005-9e31-9f1519d8054a

📥 Commits

Reviewing files that changed from the base of the PR and between 3ad99ef and c611022.

📒 Files selected for processing (1)

• .github/workflows/ci.yml

📝 Walkthrough

Walkthrough

The pull request modifies the CI workflow to expose the build version as a reusable job output and adds automated pull request creation for CLI documentation updates. The Set Version step now emits to GITHUB_OUTPUT, enabling downstream jobs to consume the version. On the main branch, new workflow steps detect meaningful changes to generated command reference docs and automatically propose updates via GitHub App token–authenticated pull requests.

Changes

CI Workflow Enhancements

Layer / File(s)	Summary
Version output publishing .github/workflows/ci.yml	The build-artifacts job exposes a version output by publishing the computed value from the Set Version step, which now writes to both GITHUB_ENV and GITHUB_OUTPUT to make the version available to downstream jobs.
Automated docs PR creation .github/workflows/ci.yml	New main-branch-only steps detect non-trivial changes to the CLI master command reference, generate a GitHub App token, and open a pull request updating the reference on the docs repository, using the published build version in the automation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• crossplane/cli#31: This PR implements the auto-update-from-CI behavior for CLI documentation by detecting generated doc changes and automatically opening pull requests to update the command reference.

Possibly related PRs

• crossplane/cli#99: Both PRs modify the docs validation flow in .github/workflows/ci.yml to target the CLI command reference at content/cli/master/command-reference.md, with this PR extending the pattern to include automated PR creation on meaningful documentation changes.

Suggested reviewers

• tampakrap
• jcogilvie
• jbw976

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and descriptively summarizes the main change: updating CLI reference documentation automatically on every merge to main.
Description check	✅ Passed	The description is directly related to the changeset, explaining the rationale for automating CLI documentation updates and referencing issue #31.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Breaking Changes	✅ Passed	PR #106 changes only .github/workflows/ci.yml (no files under apis/** or cmd/** were modified) and has no breaking-change label, so no breaking CLI API/flag changes occurred.
Feature Gate Requirement	✅ Passed	Only .github/workflows/ci.yml was modified; no changes under apis/** or other feature-behavior code were added, so the feature-flag requirement isn’t triggered.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

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/ci.yml:
- Around line 239-244: The parsing bug is that the deleted counter is assigned
from the added column; update the deleted assignment so deleted reads the second
field from diffstat instead of the first (change the deleted variable assignment
that currently uses $1 to use $2), leaving diffstat, added and changed logic
intact so the gating condition using added/deleted works correctly.
- Around line 248-256: Replace the floating action reference
"actions/create-github-app-token@v2" in the workflow step with a pinned full
commit SHA (for example use the same SHA used in .github/workflows/renovate.yml:
fee1f7d63c2ff003460e3d139729b119787bc349) so the step id "generate-token" uses a
fixed action commit; also review and document the CLI_DOCS_BOT GitHub App
permissions used by the inputs (app-id/private-key/owner/repositories) and
restrict them to the least-privilege required for creating/updating PRs in the
crossplane/docs repo (e.g., only repository contents, pull requests or checks as
needed) and confirm those minimal permissions in the workflow or repo security
notes.

🪄 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: 492c4275-2263-40cf-8611-57c28a4c6e43

📥 Commits

Reviewing files that changed from the base of the PR and between 1cfeb97 and 3ad99ef.

📒 Files selected for processing (1)

• .github/workflows/ci.yml