Skip to content

ci: enable and improve docs-sync workflow #3398

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
kronosapiens merged 2 commits into from
Feb 17, 2026
Merged

ci: enable and improve docs-sync workflow #3398

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
41c6472
ci: enable and improve docs-sync workflow
kronosapiens Feb 17, 2026
a73da96
ci: pass explicit PR URL to gh pr merge
kronosapiens Feb 17, 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
71 changes: 42 additions & 29 deletions .github/workflows/docs-sync.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@ name: doc-sync

on:
pull_request:
#types: [closed]
branches: [disabled-at-the-moment]
types: [closed]
branches: [main]
workflow_dispatch:
inputs:
commit_sha:
Expand Down Expand Up @@ -31,17 +31,22 @@ jobs:
run: |
set -e
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 }})
DIFF_BASE="${{ github.event.inputs.commit_sha }}~1"
DIFF_HEAD="${{ github.event.inputs.commit_sha }}"
Comment on lines +35 to +36
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Feb 17, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

commit_sha~1 may not resolve to the expected parent, sensei.

Line 35 uses ${{ github.event.inputs.commit_sha }}~1 as the diff base. The ~1 suffix works for linear history but can give unexpected results for merge commits (it follows only the first parent). If the manually supplied SHA is the initial commit, ~1 will fail entirely.

Consider using git diff against HEAD~1 only after verifying the commit exists and has a parent, or accept an optional base SHA input:

+      base_commit_sha:
+        description: "Base commit SHA (defaults to commit_sha~1)"
+        required: false
+        type: string

Then:

-            DIFF_BASE="${{ github.event.inputs.commit_sha }}~1"
+            DIFF_BASE="${{ github.event.inputs.base_commit_sha || format('{0}~1', github.event.inputs.commit_sha) }}"
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.github/workflows/docs-sync.yml around lines 35 - 36, The DIFF_BASE
assignment using `${{ github.event.inputs.commit_sha }}~1` can break for merge
commits or the initial commit; update the workflow to first verify the supplied
SHA (`github.event.inputs.commit_sha`) has a parent and only then set DIFF_BASE
to its parent, otherwise fall back to an explicitly provided base input (e.g.,
`github.event.inputs.base_sha`) or to a safe alternative (like `git rev-parse
--verify <sha>^`/error out with a clear message); change the DIFF_BASE/DIFF_HEAD
logic so DIFF_HEAD still uses `github.event.inputs.commit_sha` but DIFF_BASE is
computed conditionally after validating the commit parent existence.

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 }})
DIFF_BASE="${{ github.event.pull_request.base.sha }}"
DIFF_HEAD="${{ github.event.pull_request.merge_commit_sha }}"
fi
CHANGED_FILES=$(git diff --name-only "$DIFF_BASE" "$DIFF_HEAD")
DIFF_CONTENT=$(git diff "$DIFF_BASE" "$DIFF_HEAD" -- '*.rs' '*.cairo' '*.toml' '*.md' | head -c 60000)
echo "changed_files<<EOF" >> $GITHUB_OUTPUT
echo "$CHANGED_FILES" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
echo "diff_content<<EOF" >> $GITHUB_OUTPUT
echo "$DIFF_CONTENT" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
Comment on lines 33 to +49
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Feb 17, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

Potential heredoc delimiter collision can silently truncate output, sensei.

The EOF delimiter used for both changed_files and diff_content GitHub Actions outputs (Lines 44–49) will break if the diff content itself contains a line that is exactly EOF. Given that you're capturing raw git diff output (which could contain anything — file contents, test fixtures, etc.), this is a real risk. A truncated diff means Claude gets incomplete context and may make wrong documentation decisions.

Use a randomized or unique delimiter instead:

Proposed fix 
-          echo "changed_files<<EOF" >> $GITHUB_OUTPUT
+          DELIMITER="GHADELIM_$(openssl rand -hex 8)"
+          echo "changed_files<<$DELIMITER" >> $GITHUB_OUTPUT
           echo "$CHANGED_FILES" >> $GITHUB_OUTPUT
-          echo "EOF" >> $GITHUB_OUTPUT
-          echo "diff_content<<EOF" >> $GITHUB_OUTPUT
+          echo "$DELIMITER" >> $GITHUB_OUTPUT
+          DELIMITER2="GHADELIM_$(openssl rand -hex 8)"
+          echo "diff_content<<$DELIMITER2" >> $GITHUB_OUTPUT
           echo "$DIFF_CONTENT" >> $GITHUB_OUTPUT
-          echo "EOF" >> $GITHUB_OUTPUT
+          echo "$DELIMITER2" >> $GITHUB_OUTPUT
📝 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
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 }})
DIFF_BASE="${{ github.event.inputs.commit_sha }}~1"
DIFF_HEAD="${{ github.event.inputs.commit_sha }}"
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 }})
DIFF_BASE="${{ github.event.pull_request.base.sha }}"
DIFF_HEAD="${{ github.event.pull_request.merge_commit_sha }}"
fi
CHANGED_FILES=$(git diff --name-only "$DIFF_BASE" "$DIFF_HEAD")
DIFF_CONTENT=$(git diff "$DIFF_BASE" "$DIFF_HEAD" -- '*.rs' '*.cairo' '*.toml' '*.md' | head -c 60000)
echo "changed_files<<EOF" >> $GITHUB_OUTPUT
echo "$CHANGED_FILES" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
echo "diff_content<<EOF" >> $GITHUB_OUTPUT
echo "$DIFF_CONTENT" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
git fetch origin
DIFF_BASE="${{ github.event.inputs.commit_sha }}~1"
DIFF_HEAD="${{ github.event.inputs.commit_sha }}"
else
git fetch origin main
DIFF_BASE="${{ github.event.pull_request.base.sha }}"
DIFF_HEAD="${{ github.event.pull_request.merge_commit_sha }}"
fi
CHANGED_FILES=$(git diff --name-only "$DIFF_BASE" "$DIFF_HEAD")
DIFF_CONTENT=$(git diff "$DIFF_BASE" "$DIFF_HEAD" -- '*.rs' '*.cairo' '*.toml' '*.md' | head -c 60000)
DELIMITER="GHADELIM_$(openssl rand -hex 8)"
echo "changed_files<<$DELIMITER" >> $GITHUB_OUTPUT
echo "$CHANGED_FILES" >> $GITHUB_OUTPUT
echo "$DELIMITER" >> $GITHUB_OUTPUT
DELIMITER2="GHADELIM_$(openssl rand -hex 8)"
echo "diff_content<<$DELIMITER2" >> $GITHUB_OUTPUT
echo "$DIFF_CONTENT" >> $GITHUB_OUTPUT
echo "$DELIMITER2" >> $GITHUB_OUTPUT
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.github/workflows/docs-sync.yml around lines 33 - 49, The heredoc delimiter
"EOF" is reused for both outputs and can collide with raw git diff lines;
replace the fixed "EOF" delimiter usage for the GitHub Actions outputs with
unique/randomized delimiters per output (e.g., generate DELIM1 and DELIM2 with
uuidgen or $RANDOM) and use those when writing "changed_files<<$DELIM1" /
"diff_content<<$DELIM2" and their corresponding terminators, ensuring
CHANGED_FILES and DIFF_CONTENT are written between matching, unique delimiters
so the diff won't be truncated; update the echo lines that reference the
delimiters accordingly (look for the lines building CHANGED_FILES, DIFF_CONTENT
and the echo "changed_files<<EOF"/echo "diff_content<<EOF" blocks).


- name: Check if docs update needed
id: check-docs
Expand All @@ -52,12 +57,12 @@ jobs:
# Define patterns that typically require docs updates
DOCS_PATTERNS=(
"^crates/.*\.rs$"
"^crates/.*\.cairo$"
"^crates/.*\.toml$"
"^bin/.*\.rs$"
"^bin/.*\.toml$"
"^README\.md$"
"^CHANGELOG\.md$"
"package\.json$"
)

while IFS= read -r file; do
Expand Down Expand Up @@ -85,32 +90,38 @@ jobs:
uses: anthropics/claude-code-action@beta
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
model: "claude-sonnet-4-5-20250929"
direct_prompt: |
I need you to analyze the changes in this dojo repository PR and update the documentation in the dojoengine/book repository accordingly.
Analyze changes in this dojo repository and update documentation
in the dojoengine/book repository ONLY if user-facing behavior changed.

**Change Information:**
- Title: ${{ github.event.pull_request.title || format('Manual trigger for commit {0}', github.event.inputs.commit_sha) }}
- Description: ${{ github.event.pull_request.body || 'Manually triggered documentation sync' }}
- Files changed: ${{ steps.changed-files.outputs.changed_files }}
- Commit SHA: ${{ github.event.pull_request.merge_commit_sha || github.event.inputs.commit_sha }}

**Your tasks:**
1. Review the changed files and PR description to understand what functionality was added, modified, or removed
2. Check the docs-repo directory to see what documentation currently exists
3. Determine if any existing documentation needs updates or if new documentation should be created
4. If updates are needed:
- Create or update the appropriate documentation files in the docs-repo directory
- Ensure the documentation accurately reflects the current state of the dojo
- Follow the existing documentation style and structure
- Focus on user-facing changes, API changes, new features, or breaking changes

**Important guidelines:**
- Only create documentation updates if they are actually needed
- Don't document internal implementation details unless they affect usage
- If no documentation updates are needed, simply state that and exit
- DO NOT create git branches, commits, or PRs - just update the files

The docs repository is checked out in the `docs-repo` directory. Please analyze the dojo changes and update the documentation files accordingly.
**Diff of changed files:**
${{ steps.changed-files.outputs.diff_content }}
Comment on lines 94 to +105
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Feb 17, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

PR title and body are interpolated unsanitized into the prompt — injection risk, sensei.

Lines 99–100 interpolate github.event.pull_request.title and github.event.pull_request.body directly into the YAML string via ${{ }}. A PR author could craft a title or body containing YAML special characters that break the workflow, or inject prompt instructions that manipulate Claude's behavior (prompt injection).

For the YAML/shell breakage angle: since this is inside a with: block and the direct_prompt is a YAML scalar, a PR body containing unescaped YAML could corrupt the workflow. For the prompt injection angle: a malicious PR body could instruct Claude to make arbitrary file edits in the docs repo.

Consider sanitizing or truncating the PR body, or passing it via an environment variable / file rather than inline interpolation.


**Docs repo structure** (checked out in `docs-repo/`):
The site uses Vocs. Content lives in `docs-repo/docs/pages/` with these sections:
- `getting-started/` — Your First Dojo App, Understanding the Toolchain, Development Workflow
- `framework/` — world/, models/, systems/, testing/, upgrading/, configuration/
- `toolchain/` — sozo/, katana/, torii/, saya/, cainome
- `client/sdk/` — dojo.js, dojo.c, dojo.unity, dojo.unreal, dojo.godot, dojo.bevy, dojo.rust, dojo.telegram
- `tutorials/` — Dojo 101, Deploy to Mainnet, Deploy using Slot
- `libraries/` — Origami, Alexandria
- `scaling/` — Execution Sharding, Sovereign Rollups
Sidebar config is in `docs-repo/routes.ts`, imported by `docs-repo/vocs.config.ts`.

**Rules — read these carefully:**
1. DEFAULT TO NO CHANGES. Most code PRs do not need docs updates. Internal refactors, test changes, CI changes, and dependency bumps need nothing. Only proceed if there is a concrete user-facing change (new API, changed behavior, new feature, removed feature, changed configuration).
2. SINGLE CANONICAL LOCATION. Each piece of information belongs on exactly one page. Find the one page that owns the topic and make your substantive edits there. Other pages MAY add a brief cross-reference linking to the canonical page, but do NOT duplicate explanations, code samples, or configuration details across multiple pages.
3. MINIMAL EDITS. Update only the specific section affected. Do not rewrite surrounding paragraphs, add new sections for context, or reorganize existing content.
4. ONE CODE EXAMPLE per concept. If a code sample is needed, add it once in the canonical location. Do not add the same or similar examples to multiple pages.
5. Do NOT create git branches, commits, or PRs — just update files.
6. If no documentation updates are needed, state that clearly and exit.

allowed_tools: "Read,Write,Edit,MultiEdit,Glob,Grep"

Expand Down Expand Up @@ -151,7 +162,7 @@ jobs:

# Create PR
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
gh pr create \
PR_URL=$(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 }}

Expand All @@ -160,17 +171,19 @@ jobs:
- 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."
Please review the documentation changes to ensure they accurately reflect the dojo updates.")
gh pr merge "$PR_URL" --auto --squash
else
gh pr create \
PR_URL=$(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."
Please review the documentation changes to ensure they accurately reflect the dojo updates.")
gh pr merge "$PR_URL" --auto --squash
fi
else
echo "No documentation changes were made by Claude"
Expand Down