Skip to content

docs(cua-driver): wire reference auto-generation to the real docs dir + release #2088

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

Merged
f-trycua merged 3 commits into from
Jul 1, 2026
Merged

docs(cua-driver): wire reference auto-generation to the real docs dir + release #2088

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
04a8671
docs(cua-driver): drop the manual `cua-driver serve` step from the fi…
f-trycua Jul 1, 2026
2c73670
docs(cua-driver): wire reference auto-generation to the real docs dir…
f-trycua Jul 1, 2026
10961d3
docs(cua-driver): address CodeRabbit — checkout creds, set_recording …
f-trycua Jul 1, 2026
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
92 changes: 92 additions & 0 deletions .github/workflows/cd-cua-driver-docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
name: "CD: Cua Driver Reference Docs"

# On a cua-driver release tag, regenerate the auto-generated reference MDX
# (cli-reference.mdx + mcp-tools.mdx) from the released binary's `dump-docs`
# output and open a PR with the refresh. This keeps the shipped reference in
# lockstep with the released binary's CLI/MCP surface without a human having
# to remember to run `pnpm docs:generate:cua-driver` after every cut.
#
# A PR (rather than a direct push to main) keeps a human in the loop for the
# generated-content diff. The App token mirrors the identity the version-bake
# step in cd-rust-cua-driver.yml already uses for release-time repo writes.

on:
push:
tags:
- "cua-driver-rs-v*"
workflow_dispatch:

permissions:
contents: write
pull-requests: write

jobs:
regenerate-reference-docs:
name: Regenerate cua-driver reference
runs-on: macos-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0 # full history for git-tag version discovery
Comment on lines +28 to +31

@coderabbitai coderabbitai Bot Jul 1, 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.

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

sed -n '1,180p' .github/workflows/cd-cua-driver-docs.yml | cat -n

Repository: trycua/cua

Length of output: 4408

🏁 Script executed:

python3 - <<'PY'
from pathlib import Path
p = Path('.github/workflows/cd-cua-driver-docs.yml')
text = p.read_text()
for i, line in enumerate(text.splitlines(), 1):
    if 'checkout' in line.lower() or 'credentials' in line.lower() or 'github app' in line.lower() or 'git remote set-url' in line.lower() or 'pnpm install' in line.lower() or 'cargo build' in line.lower():
        print(f"{i}: {line}")
PY

Repository: trycua/cua

Length of output: 566

🏁 Script executed:

sed -n '1,140p' .github/workflows/cd-cua-driver-docs.yml | nl -ba | sed -n '1,140p'

Repository: trycua/cua

Length of output: 184

Disable persisted checkout credentials. actions/checkout leaves the repo token in git config until it is cleared later, so pnpm install and cargo build can read a write-capable credential. Set persist-credentials: false here; the workflow re-authenticates with the App token before pushing.

🧰 Tools
🪛 zizmor (1.26.1)

[warning] 28-31: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false

(artipacked)

🤖 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/cd-cua-driver-docs.yml around lines 28 - 31, The Checkout
repository step in the workflow leaves the default token persisted in git
config, which can expose write-capable credentials to later commands like pnpm
install and cargo build. Update the actions/checkout@v4 configuration in the
checkout step to disable persisted credentials, using the existing Checkout
repository action block as the reference, and keep the later App token
re-authentication flow for pushes unchanged.

Source: Linters/SAST tools

persist-credentials: false # re-auth with the App token before pushing

- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "20"

- name: Install pnpm
uses: pnpm/action-setup@v4

- name: Install docs dependencies
run: pnpm install
working-directory: docs

- name: Setup Rust toolchain
uses: dtolnay/rust-toolchain@stable

- name: Build cua-driver (release)
run: cargo build -p cua-driver --release
working-directory: libs/cua-driver/rust

- name: Regenerate reference docs
run: npx tsx scripts/docs-generators/runner.ts --library cua-driver

- name: Generate GitHub App token
id: app-token
uses: actions/create-github-app-token@v1
with:
app-id: ${{ secrets.RELEASE_APP_ID }}
private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
owner: ${{ github.repository_owner }}
repositories: ${{ github.event.repository.name }}

- name: Open PR with refreshed reference docs
env:
GH_TOKEN: ${{ steps.app-token.outputs.token }}
run: |
if git diff --quiet -- docs/content/docs/reference/cua-driver; then
echo "Reference docs already up to date; nothing to open."
exit 0
fi

BRANCH="docs/cua-driver-reference-${GITHUB_REF_NAME}"

# Re-authenticate origin with the App token so the push uses the
# bypass-enabled identity, not the default github-actions[bot]
# credentials baked in by actions/checkout.
git config --unset-all "http.https://github.com/.extraheader" || true
git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git"

git config user.name "trycua-release[bot]"
git config user.email "trycua-release[bot]@users.noreply.github.com"
git checkout -B "$BRANCH"
git add docs/content/docs/reference/cua-driver
git commit -m "docs(cua-driver): regenerate reference for ${GITHUB_REF_NAME}"
git push -u origin "$BRANCH" --force-with-lease

gh pr create --base main --head "$BRANCH" \
--title "docs(cua-driver): regenerate reference for ${GITHUB_REF_NAME}" \
--body "Auto-generated from \`cua-driver dump-docs\` at \`${GITHUB_REF_NAME}\` by the cua-driver reference-docs workflow. Only the auto-generated \`cli-reference.mdx\` and \`mcp-tools.mdx\` change; the hand-maintained sibling files are untouched." \
|| echo "PR already exists for ${BRANCH}; the push updated it."
4 changes: 2 additions & 2 deletions .github/workflows/ci-check-docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ on:
# Cua-Bot
- "libs/cuabot/src/**"
# Documentation files themselves
- "docs/content/docs/cua-driver/reference/**"
- "docs/content/docs/reference/cua-driver/**"
- "docs/content/docs/cua/reference/**"
- "docs/content/docs/cuabot/reference/**"
# Generator scripts
Expand Down Expand Up @@ -71,7 +71,7 @@ jobs:
GENERATORS=""

# Source changes
if echo "$CHANGED_FILES" | grep -q "^libs/cua-driver/rust/crates/\|^libs/cua-driver/rust/Cargo.toml\|^libs/cua-driver/rust/Cargo.lock\|^docs/content/docs/cua-driver/reference/"; then
if echo "$CHANGED_FILES" | grep -q "^libs/cua-driver/rust/crates/\|^libs/cua-driver/rust/Cargo.toml\|^libs/cua-driver/rust/Cargo.lock\|^docs/content/docs/reference/cua-driver/"; then
GENERATORS="$GENERATORS cua-driver"
fi
if echo "$CHANGED_FILES" | grep -q "^libs/lume/src/"; then
Expand Down
Loading
Loading