Add docs-sync to Github workflows #3318
Conversation
|
ohayo, sensei! WalkthroughAdds a new GitHub Actions workflow that detects docs-impacting changes on merged PRs or manual dispatch, invokes Claude to generate docs updates in the dojoengine/book repo, commits updates on a new branch, and opens a PR when changes are produced. (49 words) Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Trigger as GitHub Event
participant WF as Workflow: doc-sync
participant Repo as dojo repo
participant Docs as dojoengine/book (docs-repo)
participant Claude as Claude Code Action
participant GH as GitHub API
Trigger->>WF: pull_request closed (merged) OR workflow_dispatch(commit_sha)
WF->>Repo: actions/checkout (full history)
WF->>WF: Determine changed files (diff base vs merge OR commit vs parent)
WF->>WF: Match files against docs-impacting patterns
alt needs_update == true
WF->>Docs: Checkout docs repo (token) into docs-repo/
WF->>Claude: Prompt with summary, changed files, commit/PR context
Claude-->>WF: Proposed docs changes (if any)
alt docs changed
WF->>Docs: git config, create branch docs-update-<ts>
WF->>Docs: Commit and push changes
WF->>GH: Create PR to dojoengine/book
GH-->>WF: PR URL
else no changes
WF->>WF: Log "no changes"
end
else needs_update == false
WF->>WF: Log "no docs update needed"
end
WF->>WF: Cleanup docs-repo directory (always)
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes ✨ Finishing Touches🧪 Generate unit tests
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
Status, Documentation and Community
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (5)
.github/workflows/docs-sync.yml (5)
20-24: Tighten permissions and add resilience controls. Ohayo sensei.
id-token: writeisn’t used; drop it.- Add a job timeout to avoid hanging runs.
permissions: contents: read pull-requests: read - id-token: write + + timeout-minutes: 20Additionally, consider adding a top-level concurrency group to prevent duplicate runs:
# Top-level (add after `on:`) concurrency: group: docs-sync-${{ github.workflow }}-${{ github.event.pull_request.number || github.event.inputs.commit_sha || github.sha }} cancel-in-progress: false
55-63: Broaden doc-impact patterns (catch common doc-touching areas).Include docs/book/examples and Cairo sources which often require doc updates in this repo.
DOCS_PATTERNS=( "^crates/.*\.rs$" "^crates/.*\.toml$" "^bin/.*\.rs$" "^bin/.*\.toml$" "^README\.md$" "^CHANGELOG\.md$" "package\.json$" + "^docs/.*" + "^book/.*" + "^examples/.*" + "^contracts/.*\.cairo$" )
93-116: Minor: Prompt guideline vs. automation flow.Your prompt says “DO NOT create git branches, commits, or PRs” which is correct for the tool step, but could confuse future maintainers since the next step does exactly that. Add a brief comment clarifying that branching/PR is handled by the subsequent step.
1-1: Nit: Align naming.Workflow file is
docs-sync.ymlbutname: doc-sync. Considername: docs-syncfor consistency in the Actions UI.
77-84: Token scope check.Ensure
secrets.CREATE_PR_TOKENis a fine-grained token limited todojoengine/bookwith only the scopes needed (contents: write, pull requests). If missing or under-scoped, this job will fail on push/PR creation.I can provide a minimal set of required scopes and a setup checklist if helpful, sensei.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
.github/workflows/docs-sync.yml(1 hunks)
🧰 Additional context used
🪛 actionlint (1.7.7)
.github/workflows/docs-sync.yml
122-122: "github.event.pull_request.title" is potentially untrusted. avoid using it directly in inline scripts. instead, pass it through an environment variable. see https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions for more details
(expression)
Fix command formatting Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (3)
.github/workflows/docs-sync.yml (3)
29-41: Harden changed-file detection and shell flags.Handle squash/rebase merges (merge_commit_sha can be null), root commits (no parent), and enable strict bash. This avoids failures and false negatives. Ohayo, sensei.
- run: | - set -e + run: | + set -Eeuo pipefail if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then - # Get changed files for the specified commit - git fetch origin - CHANGED_FILES=$(git diff --name-only ${{ github.event.inputs.commit_sha }}~1 ${{ github.event.inputs.commit_sha }}) + # Get changed files for the specified commit (fallback if no parent) + git fetch --all --prune + TO="${{ github.event.inputs.commit_sha }}" + PARENT="$(git rev-list --parents -n 1 "$TO" | awk '{print $2}')" + if [ -n "$PARENT" ]; then + CHANGED_FILES="$(git diff --name-only "$PARENT" "$TO")" + else + CHANGED_FILES="$(git show --pretty='' --name-only "$TO")" + fi else - # Get list of changed files in the merged PR - git fetch origin main - CHANGED_FILES=$(git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.merge_commit_sha }}) + # Get list of changed files in the merged PR (handle squash/rebase) + git fetch origin main --depth=0 + TO="${{ github.event.pull_request.merge_commit_sha }}" + if [ -z "$TO" ] || ! git cat-file -e "$TO^{commit}" 2>/dev/null; then + TO="${{ github.event.pull_request.head.sha }}" + fi + FROM="${{ github.event.pull_request.base.sha }}" + CHANGED_FILES="$(git diff --name-only "$FROM" "$TO")" fi echo "changed_files<<EOF" >> $GITHUB_OUTPUT echo "$CHANGED_FILES" >> $GITHUB_OUTPUT echo "EOF" >> $GITHUB_OUTPUT
131-174: Fix quoting/injection risks in commit/PR creation (titles/bodies can break the shell).Write messages to files via here-docs and use -F/--body-file. This also resolves actionlint’s warning.
# Add and commit changes git add . - if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then - git commit -m "docs: Update documentation for dojo commit ${{ github.event_inputs.commit_sha }} - - Updates documentation to reflect changes made in commit: - ${{ github.event.inputs.commit_sha }} - - Manually triggered documentation sync" - else - git commit -m "docs: Update documentation for dojo PR #${{ github.event.pull_request.number }} - - Updates documentation to reflect changes made in: - ${{ github.event.pull_request.title }} - - Related dojo PR: dojoengine/dojo#${{ github.event.pull_request.number }}" - fi + if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then + cat > .git/COMMITMSG <<'MSG' +docs: Update documentation for dojo commit ${{ github.event.inputs.commit_sha }} + +Updates documentation to reflect changes made in commit: +${{ github.event.inputs.commit_sha }} + +Manually triggered documentation sync +MSG + else + cat > .git/COMMITMSG <<'MSG' +docs: Update documentation for dojo PR #${{ github.event.pull_request.number }} + +Updates documentation to reflect changes made in: +${{ github.event.pull_request.title }} + +Related dojo PR: dojoengine/dojo#${{ github.event.pull_request.number }} +MSG + fi + git commit -F .git/COMMITMSG @@ - if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then - gh pr create \ - --title "docs: Update documentation for dojo commit ${{ github.event.inputs.commit_sha }}" \ - --body "This PR updates the documentation to reflect changes made in dojoengine/dojo commit ${{ github.event.inputs.commit_sha }} - - **Commit Details:** - - Commit SHA: ${{ github.event.inputs.commit_sha }} - - Files changed: ${{ steps.changed-files.outputs.changed_files }} - - Trigger: Manual documentation sync - - Please review the documentation changes to ensure they accurately reflect the dojo updates." + if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then + cat > .git/BODY.md <<'MSG' +This PR updates the documentation to reflect changes made in dojoengine/dojo commit ${{ github.event.inputs.commit_sha }} + +**Commit Details:** +- Commit SHA: ${{ github.event.inputs.commit_sha }} +- Files changed: +${{ steps.changed-files.outputs.changed_files }} +- Trigger: Manual documentation sync + +Please review the documentation changes to ensure they accurately reflect the dojo updates. +MSG + gh pr create \ + --title "docs: Update documentation for dojo commit ${{ github.event.inputs.commit_sha }}" \ + --body-file .git/BODY.md else - gh pr create \ - --title "docs: Update documentation for dojo PR #${{ github.event.pull_request.number }}" \ - --body "This PR updates the documentation to reflect changes made in dojoengine/dojo#${{ github.event.pull_request.number }} - - **Original PR Details:** - - Title: ${{ github.event.pull_request.title }} - - Files changed: ${{ steps.changed-files.outputs.changed_files }} - - Please review the documentation changes to ensure they accurately reflect the dojo updates." + cat > .git/BODY.md <<'MSG' +This PR updates the documentation to reflect changes made in dojoengine/dojo#${{ github.event.pull_request.number }} + +**Original PR Details:** +- Title: ${{ github.event.pull_request.title }} +- Files changed: +${{ steps.changed-files.outputs.changed_files }} + +Please review the documentation changes to ensure they accurately reflect the dojo updates. +MSG + gh pr create \ + --title "docs: Update documentation for dojo PR #${{ github.event.pull_request.number }}" \ + --body-file .git/BODY.md fi
25-27: Pin third‑party actions to immutable SHAs.actions/checkout@v4 and anthropics/claude-code-action@beta are moving tags. Pin to full commit SHAs to reduce supply‑chain risk.
- uses: actions/checkout@v4 + uses: actions/checkout@<commit-sha-for-v4> @@ - uses: actions/checkout@v4 + uses: actions/checkout@<commit-sha-for-v4> @@ - uses: anthropics/claude-code-action@beta + uses: anthropics/claude-code-action@<commit-sha>Replace placeholders with the current published SHAs from each action’s repo.
Also applies to: 75-82, 83-89
🧹 Nitpick comments (5)
.github/workflows/docs-sync.yml (5)
178-180: Expose GH_TOKEN for gh CLI as well.gh prefers GH_TOKEN; set both to the same secret for robustness.
env: - GITHUB_TOKEN: ${{ secrets.CREATE_PR_TOKEN }} + GITHUB_TOKEN: ${{ secrets.CREATE_PR_TOKEN }} + GH_TOKEN: ${{ secrets.CREATE_PR_TOKEN }}
18-22: Tighten job permissions (least privilege).id-token: write isn’t used here; drop it. Keep contents/pull-requests minimal since pushes/PRs use a PAT.
permissions: - contents: read - pull-requests: read - id-token: write + contents: read + pull-requests: read
46-61: Make docs-impact detection configurable and broader.Current patterns may miss important changes. Consider expanding and/or driving from a single regex list variable or a script.
DOCS_PATTERNS=( "^crates/.*\.rs$" "^crates/.*\.toml$" "^bin/.*\.rs$" "^bin/.*\.toml$" "^README\.md$" "^CHANGELOG\.md$" "package\.json$" + "^Cargo\.toml$" + "^docs/.*" + "^book/.*" + "^examples/.*\.(rs|toml|md)$" + "^crates/.*/Cargo\.toml$" )Optionally move this into a maintained scripts/docs-patterns.txt and read it at runtime.
Also applies to: 63-74
14-22: Add timeout and concurrency control to avoid pile-ups.Prevents long‑running jobs and serializes per-PR runs.
docs-sync: if: github.event.pull_request.merged == true || github.event_name == 'workflow_dispatch' runs-on: ubuntu-latest + timeout-minutes: 30 + concurrency: + group: docs-sync-${{ github.event.pull_request.number || github.run_id }} + cancel-in-progress: false
1-1: Align naming (doc-sync vs docs-sync).For clarity, consider using the same pluralization in workflow name and job id.
-name: doc-sync +name: docs-sync
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
.github/workflows/docs-sync.yml(1 hunks)
🧰 Additional context used
🪛 actionlint (1.7.7)
.github/workflows/docs-sync.yml
120-120: "github.event.pull_request.title" is potentially untrusted. avoid using it directly in inline scripts. instead, pass it through an environment variable. see https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions for more details
(expression)
Add a
docs-syncworkflow to Github, cribbing notes from the Controller actionSummary by CodeRabbit
New Features
Chores