claude-documentation-reviewer.yml

name: Documentation Reviewer

on:
  pull_request_target:
    types: [opened, edited, reopened, synchronize]
    paths:
      - '**.md'
  issue_comment:
    types: [created]

jobs:
  claude-response:
    runs-on: ubuntu-latest
    # For issue_comment events, only run on PR comments that mention @claude
    if: |
      github.event_name == 'pull_request_target' ||
      (github.event_name == 'issue_comment' &&
       github.event.issue.pull_request &&
       contains(github.event.comment.body, '@claude'))
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - name: Get PR branch for issue_comment events
        id: pr-info
        if: github.event_name == 'issue_comment'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          PR_DATA=$(gh pr view ${{ github.event.issue.number }} --repo ${{ github.repository }} --json headRefName,headRefOid)
          echo "branch=$(echo "$PR_DATA" | jq -r '.headRefName')" >> "$GITHUB_OUTPUT"

      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          # For fix mode, check out the branch by name so git push works.
          # For review mode, check out by SHA to prevent TOCTOU attacks from forks.
          ref: ${{ github.event_name == 'issue_comment' && steps.pr-info.outputs.branch || github.event.pull_request.head.sha || github.sha }}
          fetch-depth: 0

      - name: Get changed markdown files
        id: changed-files
        if: github.event_name == 'pull_request_target'
        run: |
          BASE_SHA="${{ github.event.pull_request.base.sha }}"
          HEAD_SHA="${{ github.event.pull_request.head.sha }}"
          CHANGED_MD_FILES=$(git diff --name-only --diff-filter=ACMRT $BASE_SHA $HEAD_SHA | grep '\.md$' || true)
          if [ -z "$CHANGED_MD_FILES" ]; then
            echo "No markdown files changed"
            echo "files=" >> "$GITHUB_OUTPUT"
            echo "count=0" >> "$GITHUB_OUTPUT"
          else
            echo "Changed markdown files:"
            echo "$CHANGED_MD_FILES"
            FILES_LIST=$(echo "$CHANGED_MD_FILES" | tr '\n' ',' | sed 's/,$//')
            echo "files=$FILES_LIST" >> "$GITHUB_OUTPUT"
            echo "count=$(echo "$CHANGED_MD_FILES" | wc -l | tr -d ' ')" >> "$GITHUB_OUTPUT"
          fi

      - name: Delete existing review comment
        if: github.event_name == 'pull_request_target' && steps.changed-files.outputs.count > 0
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          PR_NUMBER=${{ github.event.pull_request.number }}
          COMMENT_IDS=$(gh api repos/${{ github.repository }}/issues/${PR_NUMBER}/comments \
            --jq '[.[] | select(.user.login == "github-actions[bot]") | select(.body | startswith("## Documentation Review")) | .id] | .[]' 2>/dev/null || true)
          for ID in $COMMENT_IDS; do
            gh api repos/${{ github.repository }}/issues/comments/${ID} -X DELETE || true
          done

      - name: Checkout system prompt repository
        uses: actions/checkout@v4
        with:
          repository: netwrix-eng/internal-agents
          token: ${{ secrets.PRIVATE_AGENTS_REPO }}
          path: system-prompt-repo
          ref: builds
          sparse-checkout: |
            engineering/technical_writing/system-prompt.md
          sparse-checkout-cone-mode: false

      - name: Read system prompt
        id: read-prompt
        run: |
          {
            echo "prompt<<EOF"
            cat system-prompt-repo/engineering/technical_writing/system-prompt.md
            echo "" # Forces a newline to prevent EOF delimiter errors
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      # Review mode: auto-triggered when markdown files change in a PR
      - name: Run documentation review
        uses: anthropics/claude-code-action@v1
        if: github.event_name == 'pull_request_target' && steps.changed-files.outputs.count > 0
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          show_full_output: true
          prompt: |
            Review ONLY the following markdown files that were changed in this PR: ${{ steps.changed-files.outputs.files }}

            Use `gh pr diff ${{ github.event.pull_request.number }}` to see the exact changes made.

            Do not review or comment on any other files (e.g., .js, .ts, .json, etc.). Focus exclusively on the documentation changes in the markdown files listed above.

            Write your complete review to /tmp/review.md. The last line of /tmp/review.md must be exactly:
            To apply all suggested fixes, reply with `@claude fix all issues`.

            Then post it with:
            gh pr comment ${{ github.event.pull_request.number }} --body-file /tmp/review.md

          claude_args: |
            --model claude-sonnet-4-5-20250929
            --allowedTools "Write,Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr comment:*)"
            --append-system-prompt "${{ steps.read-prompt.outputs.prompt }}"

      # Fix mode: triggered when someone comments @claude on a PR
      - name: Apply fixes on @claude request
        uses: anthropics/claude-code-action@v1
        if: github.event_name == 'issue_comment'
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          show_full_output: true
          claude_args: |
            --model claude-sonnet-4-5-20250929
            --allowedTools "Write,Edit,Bash(gh pr view:*),Bash(gh pr diff:*),Bash(gh pr comment:*),Bash(git config:*),Bash(git add:*),Bash(git commit:*),Bash(git push:*),Bash(git status:*),Bash(git diff:*)"
            --append-system-prompt "${{ steps.read-prompt.outputs.prompt }}"