chore(workflows): run Claude review once per PR and on manual trigger

lroolle · lroolle · commit 64306d210937 · 2025-06-23T17:29:55.000+08:00
- Update workflow to trigger only on PR open/reopen and manual comment
- Add concurrency group to ensure single review per PR at a time
- Improve documentation and add workflow example for clarity
- Move request tracing info to README and update troubleshooting steps
diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml
@@ -1,35 +1,37 @@
 name: Claude Code Review
 
 on:
-  pull_request:
-    types: [opened, synchronize]
-    # Optional: Only run on specific file changes
-    # paths:
-    #   - "src/**/*.ts"
-    #   - "src/**/*.tsx"
-    #   - "src/**/*.js"
-    #   - "src/**/*.jsx"
+  pull_request_target:
+    types: [opened, reopened]
+  issue_comment:
+    types: [created]
+  workflow_dispatch:
+
+concurrency:
+  group: "claude-review-${{ github.event.pull_request.number || github.event.issue.number }}"
+  cancel-in-progress: false
 
 jobs:
   claude-review:
-    # Optional: Filter by PR author
-    # if: |
-    #   github.event.pull_request.user.login == 'external-contributor' ||
-    #   github.event.pull_request.user.login == 'new-developer' ||
-    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+    if: |
+      github.event_name == 'pull_request_target' ||
+      (github.event_name == 'issue_comment' && 
+       github.event.issue.pull_request && 
+       contains(github.event.comment.body, '@claude'))
     
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      pull-requests: read
-      issues: read
+      pull-requests: write
+      issues: write
       id-token: write
     
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
-          fetch-depth: 1
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha || github.event.pull_request.merge_commit_sha }}
 
       - name: Run Claude Code Review
         id: claude-review
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -2,6 +2,45 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## PROJECT STRUCTURE
+
+```
+claude-code-yolo/
+├── CLAUDE.md                  # This file - project guidance for Claude
+├── README.md                  # Main documentation 
+├── CHANGELOG.md               # Version history
+├── DEV-LOGS.md               # Development journal
+├── TODO.md                   # Task tracking
+├── install.sh                # One-line installer script
+├── Makefile                  # Build automation
+├── Dockerfile                # Container image definition
+├── .dockerignore             # Docker build exclusions
+├── docker-entrypoint.sh      # Container startup script
+├── .gitignore                # Git exclusions
+├── claude.sh                 # Main wrapper script (local/Docker modes)
+├── claude-yolo               # Quick YOLO mode wrapper
+├── claudeb.sh                # Bedrock authentication helper
+│
+├── .github/                  # GitHub automation
+│   ├── ISSUE_TEMPLATE.md     # Bug report template
+│   └── workflows/            # GitHub Actions
+│       ├── ci.yml           # Pull request checks
+│       ├── release.yml      # Release automation
+│       ├── claude.yml       # Claude @mention handler
+│       └── claude-code-review.yml  # Automated code review
+│
+├── workflows/                # Development workflows
+│   ├── GIT-COMMIT.md        # Commit guidelines
+│   ├── GITHUB-PR.md         # PR creation process
+│   └── PRE-RELEASE.md       # Release checklist
+│
+└── references/              # Documentation and research
+    ├── chats/               # AI conversation logs
+    ├── claude-code/         # Official Claude Code repo reference
+    ├── claude-code-docs/    # Official documentation
+    └── code-reviews/        # AI code review examples
+```
+
 ## PROJECT PURPOSE
 
 **Claude Code YOLO wraps the Claude CLI in Docker to safely enable `--dangerously-skip-permissions` without compromising your local machine.**
@@ -102,8 +141,7 @@ Docker container automatically translates `127.0.0.1` and `localhost` to `host.d
 * "Invalid API key" - Mount both `~/.claude` and `~/.claude.json`
 * Proxy not working - Localhost auto-translates to `host.docker.internal`
 * Permission denied - Container copies auth files with proper permissions
-* Wrong auth method - Use explicit flags: `--claude`, `--api-key`, `--bedrock`
-* Claude refuses dangerous permissions - YOLO mode runs as non-root + adds `--dangerously-skip-permissions`
+* Claude refuses dangerous permissions on root user - YOLO mode runs as non-root + adds `--dangerously-skip-permissions`
 * Running in home directory - Script warns and requires confirmation, always cd to project first
 
 ## Development Tools Included
@@ -114,112 +152,3 @@ Docker container automatically translates `127.0.0.1` and `localhost` to `host.d
 **Editors**: vim, neovim, nano
 **Shell**: zsh with oh-my-zsh and plugins
 **Claude**: claude, claude-trace pre-installed
-
-## Request Tracing Support
-
-Claude Code YOLO integrates with [claude-trace](https://github.com/badlogic/lemmy/tree/main/apps/claude-trace) for detailed request logging and debugging.
-
-**Installation:**
-```bash
-npm install -g @mariozechner/claude-trace
-```
-
-**Usage:**
-```bash
-# Enable tracing in local mode
-./claude.sh --trace .
-
-# Enable tracing in YOLO mode
-./claude.sh --yolo --trace .
-
-# Bedrock with tracing
-./claudeb.sh --trace .
-```
-
-**Features:**
-- Logs all Claude API requests and responses
-- Saves trace files to `.claude-trace/` directory
-- Includes full request/response headers and timing
-- Useful for debugging authentication issues and API usage
-
-## Common Development Commands
-
-### Building and Testing
-```bash
-# Build Docker image
-make build
-
-# Rebuild without cache
-make rebuild
-
-# Test the built image
-make test
-
-# Test with current directory mounted
-make test-local
-
-# Build and test in one command
-make build-test
-
-# Open development shell
-make dev
-```
-
-### Running Claude
-```bash
-# Quick YOLO mode (recommended)
-./claude-yolo .                   # Local script
-claude-yolo .                     # If installed globally
-
-# Full wrapper options
-./claude.sh --yolo .              # YOLO mode in Docker
-./claude.sh .                     # Local mode (no Docker)
-./claude.sh --api-key .           # Use API key auth
-./claude.sh --bedrock .           # Use AWS Bedrock
-./claude.sh --vertex .            # Use Google Vertex AI
-./claude.sh --shell               # Open shell in container
-./claude.sh --trace .             # Enable request tracing
-```
-
-### Container Management
-```bash
-# Clean up Docker artifacts
-make clean
-
-# Deep clean including BuildKit cache
-make clean-all
-
-# Show image information and size
-make info
-
-# Check build context size
-make context-size
-
-# Lint Dockerfile (requires hadolint)
-make lint
-```
-
-## Debug and Troubleshooting Commands
-
-### Authentication Debugging
-```bash
-# Test different auth methods with tracing
-./claude.sh --claude --trace .    # OAuth debugging
-./claude.sh --api-key --trace .   # API key debugging
-./claude.sh --bedrock --trace .   # Bedrock debugging
-
-# Use dedicated Bedrock helper script
-./claudeb.sh --trace .            # Bedrock with model conversion
-```
-
-### Container Debugging
-```bash
-# Open shell in container for debugging
-make shell
-
-# Check container environment
-docker run --rm -it lroolle/claude-code-yolo:latest bash -c "env | sort"
-
-# Verify development tools
-docker run --rm lroolle/claude-code-yolo:latest bash -c 'python --version && node --version && go version'
-```
diff --git a/DEV-LOGS.md b/DEV-LOGS.md
@@ -5,6 +5,24 @@
 
 ## Issue Analysis: 2025-06-23
 
+### [enhancement-completed] Claude Code Review workflow simplification
+
+**Problem**: Overcomplicated workflow with manual duplicate detection using GitHub CLI.
+
+**Solution**: Adopted ChatGPT pattern with critical fixes:
+- `pull_request_target` → enables secret access for `ANTHROPIC_API_KEY`
+- Concurrency groups → automatic duplicate prevention 
+- Proper checkout ref → works for comment-triggered reviews
+- Removed complex GitHub CLI duplicate detection logic
+
+**Result**: 50% fewer lines, more reliable, follows GitHub best practices.
+
+**Status**: ✅ **COMPLETED**
+
+---
+
+## Issue Analysis: 2025-06-23
+
 ### [enhancement-completed] Clean startup message redesign
 
 **Problem**: Startup messages were excessively verbose (65+ lines) with poor UX.
diff --git a/README.md b/README.md
@@ -117,6 +117,11 @@ claude-yolo -v ~/.terraform.d:/root/.terraform.d
 - **Request Tracing**: Debug with `--trace` flag using claude-trace
 - **Docker Socket**: Optional mounting with `CLAUDE_YOLO_DOCKER_SOCKET=true`
 
+
+### Request Tracing by @badlogic `claude-trace`
+
+Claude Code YOLO integrates with [claude-trace](https://github.com/badlogic/lemmy/tree/main/apps/claude-trace) for detailed request logging and debugging.
+
 ## Docker Images
 
 Claude Code YOLO is available from multiple container registries:
diff --git a/references/examples/github_workflows_claude_review.yaml b/references/examples/github_workflows_claude_review.yaml
@@ -0,0 +1,91 @@
+# 1. **Trigger strategy**
+
+#    * **Auto review**: run on `pull_request_target` only when the PR is **opened** or **re-opened**—not on every push (`synchronize`).
+#    * **Opt-in re-review**: listen on `issue_comment` and run again only if the comment body contains `/claude-review`.
+#    * Optional `workflow_dispatch` makes the “Run workflow” button available in the UI.
+
+# 2. **One job per PR at a time**
+
+#    * Use `concurrency.group = "claude-review-${PR_NUMBER}"`; `cancel-in-progress: false` lets earlier runs finish while preventing duplicate parallel runs.
+
+# 3. **Job guard**
+
+#    * Single job guarded with an `if:` expression so it fires only for the two allowed scenarios above.
+
+# 4. **Minimal permissions**
+
+#    * `pull-requests: write` → post review comments.
+#    * `issues: write` → reply to the `/claude-review` trigger comment.
+
+# 5. **Run the Claude action**
+
+#    * Swap the placeholder `anthropic-ai/claude-code-review@v1` for whatever revision you actually use.
+
+# 6. **(Optional) Reply to manual trigger**
+
+#    * A short “review queued” reply helps contributors know their command was accepted.
+
+# The finished workflow file **`.github/workflows/claude-review.yml`** is now in the canvas—feel free to tweak the action version, the trigger phrase, or remove the reply step if you don’t need it.
+
+# ---
+
+# Auto‑run Claude code review exactly once per PR, and allow opt‑in re‑reviews
+name: "Claude Code Review"
+
+on:
+  # --- automatic run ---
+  # Trigger only when a PR is first opened or later re‑opened.
+  pull_request_target:
+    types: [opened, reopened]
+
+  # --- manual re‑review ---
+  # Listen for a PR comment that contains the magic string "/claude-review".
+  issue_comment:
+    types: [created]
+
+  # Optional: enable the "Run workflow" button in the Actions tab.
+  workflow_dispatch:
+
+# Ensure one review job per PR runs at a time under the same key
+concurrency:
+  group: "claude-review-${{ github.event.pull_request.number || github.event.issue.number }}"
+  cancel-in-progress: false
+
+jobs:
+  review:
+    # Gate so we only execute on our two allowed scenarios
+    if: |
+      github.event_name == 'pull_request_target' ||
+      (github.event_name == 'issue_comment' &&
+       github.event.issue.pull_request &&
+       contains(github.event.comment.body, '/claude-review'))
+
+    permissions:
+      pull-requests: write   # allow action to post PR comments
+      issues: write          # allow replying to the trigger comment
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: 📥 Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          # Use the PR head SHA when the workflow is comment‑triggered
+          ref: ${{ github.event.pull_request.head.sha || github.event.pull_request.merge_commit_sha }}
+
+      - name: 🤖 Run Claude review
+        # Replace with the actual action that invokes Claude
+        uses: anthropic-ai/claude-code-review@v1
+        with:
+          pull_request: "${{ github.event.pull_request.number || github.event.issue.number }}"
+
+      - name: 🗨️  Acknowledge manual trigger
+        if: github.event_name == 'issue_comment'
+        env:
+          COMMENT_ID: "${{ github.event.comment.id }}"
+        run: |
+          gh api \
+            -X POST \
+            -F body='👋 Claude review queued.' \
+            /repos/${{ github.repository }}/issues/comments/${COMMENT_ID}/replies
