fix(ci): skip Claude workflows cleanly when ANTHROPIC_API_KEY is unset

.github/workflows/claude-review.yml

@@ -4,8 +4,31 @@ on:
   pull_request:
     types: [opened, synchronize]
 
+# Two-job pattern: a tiny gate job exposes whether ANTHROPIC_API_KEY is set
+# (since `if: ${{ secrets.X != '' }}` is not allowed at job level), and the
+# review job is gated on that. When the secret is missing, the review job
+# is skipped — not failed — so a fresh fork of this template doesn't get
+# red CI before the maintainer adds the key.
 jobs:
+  check-secret:
+    runs-on: ubuntu-latest
+    outputs:
+      has_key: ${{ steps.check.outputs.has_key }}
+    steps:
+      - id: check
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          if [ -n "$ANTHROPIC_API_KEY" ]; then
+            echo "has_key=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_key=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::ANTHROPIC_API_KEY is not set in repo Actions secrets — skipping Claude review. Add the secret in Settings → Secrets and variables → Actions to enable."
+          fi
+
   review:
+    needs: check-secret
+    if: needs.check-secret.outputs.has_key == 'true'
     runs-on: ubuntu-latest
     permissions:
       contents: read

.github/workflows/claude.yml

@@ -10,13 +10,35 @@ on:
   pull_request_review:
     types: [submitted]
 
+# Two-job pattern: a tiny gate job exposes whether ANTHROPIC_API_KEY is set,
+# so the @claude responder is skipped (not failed) when the secret is
+# missing. See claude-review.yml for the same pattern.
 jobs:
+  check-secret:
+    runs-on: ubuntu-latest
+    outputs:
+      has_key: ${{ steps.check.outputs.has_key }}
+    steps:
+      - id: check
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          if [ -n "$ANTHROPIC_API_KEY" ]; then
+            echo "has_key=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_key=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::ANTHROPIC_API_KEY is not set in repo Actions secrets — skipping @claude responder. Add the secret in Settings → Secrets and variables → Actions to enable."
+          fi
+
   claude:
+    needs: check-secret
     if: |
-      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
-      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
-      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
-      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+      needs.check-secret.outputs.has_key == 'true' && (
+        (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+        (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+        (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+        (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+      )
     runs-on: ubuntu-latest
     permissions:
       contents: write

docs/integrations.md

@@ -10,7 +10,12 @@ issues, and review comments.
 `.github/workflows/claude-review.yml` — runs a review pass on every new
 PR or push to an open PR.
 
-Both require `ANTHROPIC_API_KEY` in the repo's Actions secrets. See the
+Both require `ANTHROPIC_API_KEY` in the repo's Actions secrets. **If the
+secret is not set, both workflows skip cleanly** (a `check-secret` gate
+job emits a workflow notice and the responder/review job is marked
+*skipped*, not failed) — so a fresh fork doesn't get red CI on every PR
+before you've configured the key. Add the secret at *Settings → Secrets
+and variables → Actions* to enable. See the
 [Claude Code GitHub Actions doc](https://code.claude.com/docs/en/github-actions).
 
 ## GitLab CI/CD