fix: Add API key fallback for Claude Code review workflow

[manavgup]

Add support for ANTHROPIC_API_KEY as fallback authentication method in Claude Code review workflow to handle OAuth token expiration/revocation.

This fixes the CI failure where CLAUDE_CODE_OAUTH_TOKEN was missing or expired:

• OAuth token preferred (for Pro/Max users)
• API key as fallback (for API key users)
• Action will use whichever is available

Related: PR #452 CI failure
Issue: OAuth tokens expired in October 2025

🤖 Generated with Claude Code

[github-actions]

🚀 Development Environment Options

This repository supports Dev Containers for a consistent development environment.

Option 1: GitHub Codespaces (Recommended)

Create a cloud-based development environment:

1. Click the green Code button above
2. Select the Codespaces tab
3. Click Create codespace on claude/review-pr-452-011CUNhu6zJeqqJWY8sRP9ZJ
4. Wait 2-3 minutes for environment setup
5. Start coding with all tools pre-configured!

Option 2: VS Code Dev Containers (Local)

Use Dev Containers on your local machine:

1. Install Docker Desktop
2. Install VS Code
3. Install the Dev Containers extension
4. Clone this PR branch locally
5. Open in VS Code and click "Reopen in Container" when prompted

Option 3: Traditional Local Setup

Set up the development environment manually:

# Clone the repository
git clone https://github.com/manavgup/rag_modulo.git
cd rag_modulo
git checkout claude/review-pr-452-011CUNhu6zJeqqJWY8sRP9ZJ

# Initialize development environment
make dev-init
make dev-build
make dev-up
make dev-validate

Available Commands

Once in your development environment:

make help           # Show all available commands
make dev-validate   # Validate environment setup
make test-atomic    # Run atomic tests
make test-unit      # Run unit tests
make lint          # Run linting

Services Available

When running make dev-up:

• Backend API: http://localhost:8000
• Frontend: http://localhost:3000
• MLflow: http://localhost:5001

---

This automated message helps reviewers quickly set up the development environment.

[github-actions]

Pull Request Review: Add API Key Fallback for Claude Code Review Workflow

Overview

This PR adds ANTHROPIC_API_KEY as a fallback authentication method for the Claude Code review workflow to handle OAuth token expiration scenarios.

---

✅ Positive Aspects

1. Resilience & Availability

• Good: Provides graceful degradation when OAuth tokens expire
• Good: Maintains workflow functionality without manual intervention
• Good: Follows the fail-safe pattern for authentication

2. Minimal & Focused Change

• Good: Single-purpose change affecting only authentication
• Good: No unnecessary refactoring or scope creep
• Good: Clear and concise implementation (2 lines changed)

3. Documentation

• Good: Inline comment explains authentication preference hierarchy
• Good: PR description clearly explains the motivation and fallback mechanism

---

⚠️ Concerns & Recommendations

1. Secret Management & Security 🔒

Issue: Adding ANTHROPIC_API_KEY increases the attack surface for secret exposure.

Current State:

• The repository has comprehensive secret scanning (detect-secrets, Gitleaks, TruffleHog)
• .gitleaks.toml already includes Anthropic API key detection:

  [[rules]]
      id = "anthropic-api-key"
      description = "Anthropic API Key"
      regex = '''sk-ant-api[0-9A-Za-z\-]{95}'''
      keywords = ["sk-ant-", "ANTHROPIC_API_KEY"]

Recommendation:
✅ No changes needed - The existing secret management infrastructure (per docs/development/secret-management.md) already covers Anthropic API keys. The 3-layer defense-in-depth approach will catch any accidental exposure.

2. Authentication Preference Order 📝

Issue: The claude-code-action@v1 action's internal logic for preferring OAuth over API key is not documented in this repository.

Questions:

1. Does the action use OAuth token first, then fall back to API key automatically?
2. What happens if both secrets are missing?
3. What happens if both secrets are present but OAuth token is expired?

Recommendation:

# Suggested comment enhancement
# Authentication hierarchy (handled by claude-code-action):
# 1. OAuth token (preferred for Pro/Max users)
# 2. API key (fallback for API key users or OAuth expiration)
# At least one must be configured in GitHub Secrets
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

3. Inconsistency with claude.yml 🔄

Issue: The existing .github/workflows/claude.yml (lines 42) only uses claude_code_oauth_token without API key fallback.

Current State:

• claude-code-review.yml: Has OAuth + API key fallback ✅
• claude.yml: Only has OAuth token ❌

Recommendation:
For consistency and resilience, consider applying the same fallback pattern to claude.yml:

# .github/workflows/claude.yml (line 42)
uses: anthropics/claude-code-action@v1
with:
  claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
  anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}  # Add this

4. Testing & Validation 🧪

Issue: No evidence of testing the fallback behavior.

Recommendation:
Before merging, validate:

1. OAuth token only: Remove API key secret temporarily, verify workflow succeeds
2. API key only: Remove OAuth token, verify workflow succeeds with API key fallback
3. Both missing: Verify workflow fails gracefully with clear error message
4. Expired OAuth token: Verify automatic fallback to API key

Test command (after setting secrets):

# Trigger workflow manually to test
gh workflow run claude-code-review.yml --ref claude/review-pr-452-011CUNhu6zJeqqJWY8sRP9ZJ

5. Documentation Updates 📚

Issue: No updates to repository documentation about the new authentication option.

Recommendation:
Update the following files:

1. docs/development/ai-assisted-workflow.md (Setup section):

   ### Setup (One-Time)
   
   1. **Add Secrets** (GitHub Settings → Secrets):

   Option 1: OAuth token (preferred for Claude Pro/Max users)

   CLAUDE_CODE_OAUTH_TOKEN=

   Option 2: API key (fallback or for API key users)

   ANTHROPIC_API_KEY=<from https://console.anthropic.com>

   Note: At least one must be configured

   GEMINI_API_KEY=<from https://aistudio.google.com/app/apikey>

2. README.md (if it mentions Claude Code setup)

3. Consider adding: docs/ci-cd/claude-code-authentication.md explaining:

   • When to use OAuth vs API key
   • Token rotation procedures
   • Troubleshooting authentication failures

---

🔍 Code Quality Assessment

Aspect	Rating	Notes
Code Quality	✅ Excellent	Clean, minimal change
Best Practices	⚠️ Good	Missing documentation updates
Security	✅ Good	Existing secret scanning covers new secret type
Testing	⚠️ Needs Work	No evidence of fallback testing
Consistency	⚠️ Needs Work	claude.yml should have same pattern
Documentation	⚠️ Needs Work	Missing doc updates

---

🎯 Summary & Action Items

Required Before Merge ✋

1. Test the fallback behavior (see Testing & Validation section)
2. Update claude.yml with same API key fallback for consistency
3. Update documentation (at minimum: docs/development/ai-assisted-workflow.md)

Recommended (Can be separate PR) 💡

1. Add troubleshooting guide for Claude Code authentication
2. Consider adding workflow dispatch for manual testing
3. Add example .env.example entry: ANTHROPIC_API_KEY=sk-ant-api...placeholder

Low Priority 🔖

1. Monitor OAuth token expiration patterns to determine renewal cadence
2. Consider adding workflow status badge to README showing Claude review status

---

📊 Risk Assessment

Risk	Severity	Mitigation
Secret exposure	Low	✅ Covered by existing secret scanning
Authentication failure	Medium	⚠️ Test both auth methods before merge
Inconsistent behavior	Low	⚠️ Apply same pattern to claude.yml
Documentation gap	Low	⚠️ Update setup docs

---

🚀 Verdict

Conditional Approval ⚠️

The core implementation is sound and addresses the immediate OAuth token expiration issue. However, testing validation and documentation updates are needed before merging to ensure reliability and maintainability.

Estimated effort to address: ~20-30 minutes (testing + doc updates)

---

Generated by Claude Code Review
Following repository guidelines from CLAUDE.md