use github app for docs sync (#666)

* use github app

* test

* improve

* improve access

* fix the token

* fix naming for the automatic token

* update comment marker

* another iteration

* update

* all good, keep only the workflows

Author: whoiskatrin

.github/workflows/release.yml

@@ -44,6 +44,6 @@ jobs:
           version: npx tsx .github/changeset-version.ts
           publish: npx tsx .github/changeset-publish.ts
         env:
-          GITHUB_TOKEN: ${{ secrets.AGENTS_GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}
           NPM_PUBLISH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}

.github/workflows/sync-docs.yml

@@ -13,6 +13,14 @@ jobs:
       pull-requests: write
       id-token: write
     steps:
+      - name: Generate GitHub App token
+        id: generate-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.GH_APP_ID }}
+          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
+          owner: cloudflare
+
       - name: Checkout source repository
         uses: actions/checkout@v4
         with:
@@ -23,45 +31,25 @@ jobs:
         id: changed-files
         run: |
           git fetch origin ${{ github.event.pull_request.base.ref }}
-          git diff --name-only origin/${{ github.event.pull_request.base.ref }}...HEAD > changed_files.txt
-          echo "Changed files:"
-          cat changed_files.txt
-          grep '^docs/.*\.md$' changed_files.txt > docs_changed.txt || echo "No docs changed"
-
-      - name: Get file contents and diffs
-        id: get-diffs
-        run: |
-          mkdir -p /tmp/diffs
-          touch /tmp/diffs/changes.txt
-
-          # Capture all changed files and their diffs
-          while IFS= read -r file; do
-            echo "=== $file ===" >> /tmp/diffs/changes.txt
-            git diff origin/${{ github.event.pull_request.base.ref }}...HEAD -- "$file" >> /tmp/diffs/changes.txt
-            echo -e "\n\n" >> /tmp/diffs/changes.txt
-          done < changed_files.txt
-
-          # Always run - let Claude decide if docs are needed
-          echo "skip=false" >> $GITHUB_OUTPUT
+          CHANGED_FILES=$(git diff --name-only origin/${{ github.event.pull_request.base.ref }}...HEAD | tr '\n' ',' | sed 's/,$//')
+          echo "changed_files=$CHANGED_FILES" >> $GITHUB_OUTPUT
+          echo "Changed files: $CHANGED_FILES"
 
       - name: Checkout cloudflare-docs repository
-        if: steps.get-diffs.outputs.skip != 'true'
         uses: actions/checkout@v4
         with:
           repository: cloudflare/cloudflare-docs
-          token: ${{ secrets.AGENTS_GITHUB_TOKEN }}
+          token: ${{ steps.generate-token.outputs.token }}
           path: cloudflare-docs
 
       - name: Create branch in cloudflare-docs
-        if: steps.get-diffs.outputs.skip != 'true'
         run: |
           cd cloudflare-docs
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git checkout -b sync-docs-pr-${{ github.event.pull_request.number }}
 
       - name: Create prompt for Claude Code
-        if: steps.get-diffs.outputs.skip != 'true'
         id: create-prompt
         run: |
           # Store PR metadata in environment variables to avoid shell escaping issues
@@ -72,30 +60,32 @@ jobs:
           cat > /tmp/claude_prompt.md << EOF
           # Intelligent Documentation Sync Task
 
-          ⚠️ **CRITICAL INSTRUCTION**: All PR metadata is provided in the Context section below. 
-          DO NOT run \`gh pr view\`, \`gh api\`, or any other command to fetch PR information from GitHub.
-          The PR number, title, and URL below are the ONLY source of truth. Use them EXACTLY as written.
-
           ## Context
           - **Source Repository:** ${{ github.repository }}
           - **Original PR Number:** ${PR_NUMBER}
           - **Original PR Title:** ${PR_TITLE}
           - **Original PR URL:** ${PR_URL}
+          - **Changed Files:** ${{ steps.changed-files.outputs.changed_files }}
           - **PR Description:**
           ${{ github.event.pull_request.body }}
 
-          ## Changed Files and Diffs
-          $(cat /tmp/diffs/changes.txt)
+          ⚠️ **IMPORTANT**: All PR metadata above is the ONLY source of truth. Use these values EXACTLY as written.
+          DO NOT fetch PR title/URL from GitHub APIs.
 
           ## Your Task: Evaluate and Act
 
+          **First, gather the information you need:**
+          1. Review the list of changed files above
+          2. Use \`gh pr diff ${PR_NUMBER}\` to see the full diff for this PR
+          3. Use the Read tool to examine specific files if needed
+
           You have access to two repositories:
           1. The current directory (our main repo at ${{ github.repository }})
           2. ./cloudflare-docs (already cloned with branch sync-docs-pr-${{ github.event.pull_request.number }} checked out)
 
           **Step 1: Evaluate if Documentation Sync is Needed**
 
-          Please review the changes in this PR and determine if they require documentation updates in cloudflare-docs:
+          Review the changes and determine if they require documentation updates in cloudflare-docs:
 
           - **ALWAYS sync if ANY of these are true:**
             - Documentation files in docs/ were directly changed (even if other non-doc files also changed)
@@ -130,20 +120,23 @@ jobs:
              Run exactly: `cd cloudflare-docs && git push origin sync-docs-pr-${PR_NUMBER}`
 
           7. **CRITICAL - Create or update PR in cloudflare-docs:**
-             ⚠️ **CRITICAL**: 
-             - DO NOT fetch PR data from GitHub API to get title/description
-             - DO NOT add your own description or summary
-             - Use ONLY the PR_NUMBER, PR_TITLE, and PR_URL from the Context section above
-             
-             First check if PR already exists, then create or update:
+             ⚠️ **CRITICAL**: Use the exact PR_NUMBER, PR_TITLE, and PR_URL values from the Context section above.
+
+             Copy and run this EXACT script (replace PLACEHOLDER values with actual values from Context):
              ```bash
+             # Set variables from Context section above
+             PR_NUMBER="PLACEHOLDER_PR_NUMBER"
+             PR_TITLE="PLACEHOLDER_PR_TITLE"
+             PR_URL="PLACEHOLDER_PR_URL"
+
              # Check if PR already exists
              EXISTING_PR=$(gh pr list --repo cloudflare/cloudflare-docs --head sync-docs-pr-${PR_NUMBER} --json number --jq '.[0].number')
-             
+
+             # Create PR title and body
              PR_TITLE_TEXT="📚 Sync docs from cloudflare/agents#${PR_NUMBER}: ${PR_TITLE}"
              PR_BODY_TEXT="Syncs documentation changes from [cloudflare/agents#${PR_NUMBER}](${PR_URL}): **${PR_TITLE}**"
-             
-             if [ -n "$EXISTING_PR" ]; then
+
+             if [ -n "$EXISTING_PR" ] && [ "$EXISTING_PR" != "null" ]; then
                # Update existing PR
                echo "Updating existing PR #$EXISTING_PR"
                gh pr edit $EXISTING_PR --repo cloudflare/cloudflare-docs --title "$PR_TITLE_TEXT" --body "$PR_BODY_TEXT"
@@ -153,73 +146,8 @@ jobs:
                gh pr create --repo cloudflare/cloudflare-docs --base main --head sync-docs-pr-${PR_NUMBER} --title "$PR_TITLE_TEXT" --body "$PR_BODY_TEXT"
              fi
              ```
-             
-             DO NOT modify the PR_TITLE_TEXT or PR_BODY_TEXT variables.
-
-          8. **CRITICAL - Comment on original PR:**
-             ⚠️ **IMPORTANT**: Execute this ENTIRE script as ONE command. Do not split into multiple executions.
-             
-             Copy and run this complete bash script:
-             ```bash
-             #!/bin/bash
-             set -e
-             
-             echo "=== Step 8: Managing PR comment ==="
-             
-             # Get the docs PR URL
-             DOCS_PR_URL=$(gh pr list --repo cloudflare/cloudflare-docs --head sync-docs-pr-${PR_NUMBER} --json url --jq '.[0].url')
-             echo "Docs PR URL: $DOCS_PR_URL"
-             
-             # Find existing comment with our unique marker
-             EXISTING_COMMENT_ID=$(gh api "repos/cloudflare/agents/issues/${PR_NUMBER}/comments" \
-               --jq '.[] | select(.body | contains("<!-- DOCS-SYNC-AUTOMATION -->")) | .id' \
-               | head -n 1)
-             
-             # Prepare comment body (note the unique marker at the start)
-             COMMENT_BODY=\$(printf '%s\n\n%s\n\n%s' \\
-               '<!-- DOCS-SYNC-AUTOMATION -->' \\
-               "📚 **Documentation sync PR:** \$DOCS_PR_URL" \\
-               '_This comment is automatically updated when the PR changes._')
-             
-             # Update existing or create new comment
-             if [ -n "$EXISTING_COMMENT_ID" ] && [ "$EXISTING_COMMENT_ID" != "null" ]; then
-               echo "Found existing comment ID: $EXISTING_COMMENT_ID - updating it"
-               gh api --method PATCH \
-                 "repos/cloudflare/agents/issues/comments/$EXISTING_COMMENT_ID" \
-                 -f body="$COMMENT_BODY"
-               echo "✅ Updated existing comment"
-             else
-               echo "No existing comment found - creating new one"
-               gh pr comment ${PR_NUMBER} \
-                 --repo cloudflare/agents \
-                 --body "$COMMENT_BODY"
-               echo "✅ Created new comment"
-             fi
-             
-             # Cleanup any duplicate comments (keep only the newest)
-             ALL_COMMENT_IDS=$(gh api "repos/cloudflare/agents/issues/${PR_NUMBER}/comments" \
-               --jq '.[] | select(.body | contains("<!-- DOCS-SYNC-AUTOMATION -->")) | .id')
-             
-             COMMENT_COUNT=$(echo "$ALL_COMMENT_IDS" | wc -l | tr -d ' ')
-             
-             if [ "$COMMENT_COUNT" -gt 1 ]; then
-               echo "⚠️ Found $COMMENT_COUNT duplicate comments - cleaning up"
-               # Keep the last one (newest), delete others
-               echo "$ALL_COMMENT_IDS" | head -n -1 | while read -r OLD_ID; do
-                 if [ -n "$OLD_ID" ]; then
-                   echo "Deleting old comment ID: $OLD_ID"
-                   gh api --method DELETE "repos/cloudflare/agents/issues/comments/$OLD_ID"
-                 fi
-               done
-               echo "✅ Cleaned up duplicate comments"
-             else
-               echo "✅ Only one comment exists - no cleanup needed"
-             fi
-             
-             echo "=== Step 8 complete ==="
-             ```
 
-          ⚠️ THE TASK IS NOT COMPLETE UNTIL ALL 8 STEPS ARE DONE. Do not stop after editing files.
+          ⚠️ THE TASK IS NOT COMPLETE UNTIL ALL 7 STEPS ARE DONE. Do not stop after editing files.
 
           ## Documentation Writing Guidelines (Diátaxis Framework)
 
@@ -299,12 +227,11 @@ jobs:
           echo "PROMPT_EOF" >> $GITHUB_OUTPUT
 
       - name: Run Claude Code to create adapted PR
-        if: steps.get-diffs.outputs.skip != 'true'
         uses: anthropics/claude-code-action@v1
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-          github_token: ${{ secrets.GITHUB_TOKEN }}
+          github_token: ${{ steps.generate-token.outputs.token }}
           prompt: ${{ steps.create-prompt.outputs.prompt }}
-          claude_args: "--allowed-tools Bash,Edit,Write"
+          claude_args: '--allowed-tools "Read,Edit,Write,Bash"'
         env:
-          GH_TOKEN: ${{ secrets.AGENTS_GITHUB_TOKEN }}
+          GH_TOKEN: ${{ steps.generate-token.outputs.token }}