Claude Code 与 GitHub Actions 集成指南

为什么要集成 Claude Code 到 GitHub Actions？

将 Claude Code 集成到 GitHub Actions 工作流中，可以实现：

🔍 自动代码审查 - 在 PR 时自动进行代码质量检查
🧪 智能测试生成 - 自动为新代码生成测试用例
📝 文档自动更新 - 根据代码变更自动更新文档
🐛 漏洞扫描 - 检测潜在的安全问题和代码缺陷
⚡ 性能优化建议 - 提供代码性能改进方案

快速开始

设置 GitHub Secrets

首先，需要在 GitHub 仓库中配置 Claude API 密钥：

进入仓库的 Settings → Secrets and variables → Actions
点击 New repository secret
添加以下密钥：
- Name: CLAUDE_API_KEY
- Value: 你的 Claude API 密钥

基础工作流示例

1. 自动代码审查

创建 .github/workflows/claude-review.yml：

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  review:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 获取完整历史以便比较
      
      - name: Setup Claude Code
        uses: anthropics/claude-code-action@v1
        with:
          api-key: ${{ secrets.CLAUDE_API_KEY }}
          model: claude-3-opus-20240229
      
      - name: Get changed files
        id: changed-files
        uses: tj-actions/changed-files@v41
        
      - name: Review code changes
        run: |
          echo "## 🤖 Claude Code Review" >> $GITHUB_STEP_SUMMARY
          
          for file in ${{ steps.changed-files.outputs.all_changed_files }}; do
            echo "### Reviewing: $file" >> $GITHUB_STEP_SUMMARY
            
            claude-code review "$file" \
              --output markdown \
              --focus "security,performance,best-practices" \
              >> $GITHUB_STEP_SUMMARY
          done
      
      - name: Comment on PR
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const summary = fs.readFileSync(process.env.GITHUB_STEP_SUMMARY, 'utf8');
            
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: summary
            });

2. 自动生成测试

创建 .github/workflows/claude-tests.yml：

name: Generate Tests with Claude

on:
  push:
    branches: [main, develop]
    paths:
      - 'src/**/*.js'
      - 'src/**/*.ts'
      - 'src/**/*.py'

jobs:
  generate-tests:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - name: Setup Claude Code
        uses: anthropics/claude-code-action@v1
        with:
          api-key: ${{ secrets.CLAUDE_API_KEY }}
      
      - name: Identify untested code
        id: find-untested
        run: |
          # 查找没有对应测试文件的源文件
          find src -type f \( -name "*.js" -o -name "*.ts" \) | while read file; do
            test_file="${file%.js}.test.js"
            test_file="${test_file%.ts}.test.ts"
            if [ ! -f "$test_file" ]; then
              echo "$file" >> untested_files.txt
            fi
          done
      
      - name: Generate tests
        run: |
          if [ -f untested_files.txt ]; then
            while read file; do
              echo "Generating tests for: $file"
              
              claude-code generate-test "$file" \
                --framework jest \
                --coverage 80 \
                --output "${file%.js}.test.js"
            done < untested_files.txt
          fi
      
      - name: Create PR with tests
        uses: peter-evans/create-pull-request@v5
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          commit-message: "test: add automated tests via Claude Code"
          title: "🧪 Add automated tests"
          body: |
            ## Automated Test Generation
            
            This PR adds test files generated by Claude Code for previously untested code.
            
            ### Files covered:
            - See changed files below
            
            Please review the generated tests before merging.
          branch: claude/auto-tests

3. 文档自动生成

创建 .github/workflows/claude-docs.yml：

name: Update Documentation

on:
  push:
    branches: [main]
    paths:
      - 'src/**/*.js'
      - 'src/**/*.ts'
      - 'src/**/*.py'

jobs:
  update-docs:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Claude Code
        uses: anthropics/claude-code-action@v1
        with:
          api-key: ${{ secrets.CLAUDE_API_KEY }}
      
      - name: Generate API documentation
        run: |
          # 生成 API 文档
          claude-code generate-docs \
            --input "src/**/*.{js,ts}" \
            --output docs/api/ \
            --format markdown \
            --include-examples
      
      - name: Update README
        run: |
          # 更新 README 中的 API 部分
          claude-code update-readme \
            --section "API Reference" \
            --source docs/api/
      
      - name: Generate changelog
        run: |
          # 基于最近的提交生成更新日志
          claude-code generate-changelog \
            --since "last-tag" \
            --output CHANGELOG.md \
            --format conventional
      
      - name: Commit documentation
        run: |
          git config user.name "Claude Bot"
          git config user.email "[email protected]"
          git add docs/ README.md CHANGELOG.md
          git diff --staged --quiet || git commit -m "docs: update documentation [skip ci]"
          git push

高级用例

1. 安全扫描工作流

name: Security Scan with Claude

on:
  schedule:
    - cron: '0 0 * * 1'  # 每周一运行
  workflow_dispatch:  # 手动触发

jobs:
  security-scan:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Claude Code
        uses: anthropics/claude-code-action@v1
        with:
          api-key: ${{ secrets.CLAUDE_API_KEY }}
          model: claude-3-opus-20240229
      
      - name: Security audit
        run: |
          claude-code security-scan \
            --deep \
            --include-dependencies \
            --output security-report.json
      
      - name: Check for critical issues
        id: check-critical
        run: |
          critical=$(jq '.issues[] | select(.severity == "critical")' security-report.json)
          if [ ! -z "$critical" ]; then
            echo "has_critical=true" >> $GITHUB_OUTPUT
          fi
      
      - name: Create issue if critical
        if: steps.check-critical.outputs.has_critical == 'true'
        uses: actions/github-script@v7
        with:
          script: |
            const report = require('./security-report.json');
            const critical = report.issues.filter(i => i.severity === 'critical');
            
            await github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: '🚨 Critical security issues detected',
              body: `Claude Code detected ${critical.length} critical security issues.
              
              Please review the security report immediately.`,
              labels: ['security', 'critical']
            });

2. 性能优化建议

name: Performance Analysis

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  performance:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Setup Claude Code
        uses: anthropics/claude-code-action@v1
        with:
          api-key: ${{ secrets.CLAUDE_API_KEY }}
      
      - name: Analyze performance
        run: |
          # 分析性能瓶颈
          claude-code analyze-performance \
            --compare-with origin/main \
            --metrics "time-complexity,space-complexity,database-queries" \
            --output perf-report.md
      
      - name: Generate optimization suggestions
        run: |
          claude-code suggest-optimizations \
            --input perf-report.md \
            --priority high \
            --output suggestions.md
      
      - name: Comment suggestions on PR
        if: github.event_name == 'pull_request'
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          header: performance
          path: suggestions.md

3. 代码质量门控

name: Code Quality Gate

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  quality-check:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Claude Code
        uses: anthropics/claude-code-action@v1
        with:
          api-key: ${{ secrets.CLAUDE_API_KEY }}
      
      - name: Run quality checks
        id: quality
        run: |
          # 运行多项质量检查
          claude-code quality-check \
            --checks "complexity,duplication,naming,solid-principles" \
            --threshold 80 \
            --format json \
            --output quality-report.json
          
          # 提取分数
          score=$(jq '.overall_score' quality-report.json)
          echo "score=$score" >> $GITHUB_OUTPUT
      
      - name: Enforce quality gate
        if: steps.quality.outputs.score < 80
        run: |
          echo "❌ Code quality score: ${{ steps.quality.outputs.score }}/100"
          echo "Minimum required: 80/100"
          exit 1
      
      - name: Post success comment
        if: steps.quality.outputs.score >= 80
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `✅ Code quality check passed: ${{ steps.quality.outputs.score }}/100`
            });

自定义 Claude Code Action

创建自定义的 Claude Code Action 来复用配置：

.github/actions/claude-setup/action.yml:

name: 'Setup Claude Code'
description: 'Setup Claude Code with organization defaults'

inputs:
  api-key:
    description: 'Claude API Key'
    required: true
  model:
    description: 'Claude model to use'
    default: 'claude-3-opus-20240229'
  config-file:
    description: 'Path to Claude config file'
    default: '.claude/config.yml'

runs:
  using: 'composite'
  steps:
    - name: Install Claude Code CLI
      shell: bash
      run: |
        curl -fsSL https://claude.ai/install.sh | sh
        echo "$HOME/.claude/bin" >> $GITHUB_PATH
    
    - name: Configure Claude Code
      shell: bash
      run: |
        claude-code config set api-key "${{ inputs.api-key }}"
        claude-code config set model "${{ inputs.model }}"
        
        if [ -f "${{ inputs.config-file }}" ]; then
          claude-code config load "${{ inputs.config-file }}"
        fi
    
    - name: Verify installation
      shell: bash
      run: |
        claude-code --version
        claude-code config show

配置文件示例

`.claude/config.yml`

# Claude Code 配置
model: claude-3-opus-20240229
temperature: 0.7
max_tokens: 4000

# 代码审查规则
review:
  focus:
    - security
    - performance
    - best-practices
    - accessibility
  ignore:
    - node_modules/
    - dist/
    - "*.min.js"
  rules:
    max-complexity: 10
    max-line-length: 100
    require-jsdoc: true

# 测试生成配置
test:
  framework: jest
  coverage-threshold: 80
  mock-external: true
  include-edge-cases: true

# 文档生成配置
docs:
  format: markdown
  include-examples: true
  include-types: true
  output-dir: docs/

# 安全扫描配置
security:
  scan-dependencies: true
  check-secrets: true
  owasp-top-10: true

`.claude/prompts/review.md`

自定义审查提示词：

# 代码审查指南

请按照以下标准审查代码：

## 必须检查项
- [ ] 没有硬编码的密钥或密码
- [ ] 输入验证和清理
- [ ] 错误处理完善
- [ ] 没有 SQL 注入风险
- [ ] 没有 XSS 漏洞

## 代码质量
- [ ] 函数单一职责
- [ ] 命名清晰明确
- [ ] 适当的注释
- [ ] DRY 原则
- [ ] SOLID 原则

## 性能考虑
- [ ] 避免 N+1 查询
- [ ] 适当的缓存策略
- [ ] 异步操作处理
- [ ] 资源清理

请为每个问题提供：
1. 问题描述
2. 严重程度（低/中/高/严重）
3. 修复建议
4. 代码示例（如果适用）

最佳实践

1. 成本控制

- name: Cost control
  run: |
    # 设置 token 限制
    export CLAUDE_MAX_TOKENS=2000
    
    # 只审查关键文件
    claude-code review \
      --files "src/api/**/*.js" \
      --max-files 10

2. 缓存优化

- name: Cache Claude responses
  uses: actions/cache@v3
  with:
    path: ~/.claude/cache
    key: claude-${{ hashFiles('**/*.js') }}
    restore-keys: |
      claude-

3. 并行处理

- name: Parallel analysis
  run: |
    # 并行运行多个分析任务
    claude-code review src/ --output review.json &
    claude-code security-scan --output security.json &
    claude-code test-coverage --output coverage.json &
    wait
    
    # 合并报告
    jq -s '.[0] * .[1] * .[2]' review.json security.json coverage.json > report.json

4. 条件执行

- name: Conditional review
  if: |
    contains(github.event.pull_request.labels.*.name, 'needs-review') ||
    github.event.pull_request.draft == false
  run: |
    claude-code review --thorough

故障排除

常见问题

1. API 限流错误

- name: Retry with backoff
  uses: nick-fields/retry@v2
  with:
    timeout_minutes: 10
    max_attempts: 3
    retry_wait_seconds: 30
    command: claude-code review

2. 大文件处理

- name: Handle large files
  run: |
    # 分割大文件
    find . -size +100k -type f | while read file; do
      split -l 500 "$file" "${file}.part"
      for part in ${file}.part*; do
        claude-code review "$part"
      done
    done

3. 矩阵构建

strategy:
  matrix:
    directory: [frontend, backend, shared]
    
- name: Review by directory
  run: |
    claude-code review ${{ matrix.directory }}/

监控和报告

Slack 通知集成

- name: Send to Slack
  if: always()
  uses: slackapi/slack-github-action@v1
  with:
    payload: |
      {
        "text": "Claude Code Analysis Complete",
        "blocks": [{
          "type": "section",
          "text": {
            "type": "mrkdwn",
            "text": "*Repository:* ${{ github.repository }}\n*Score:* ${{ steps.quality.outputs.score }}/100"
          }
        }]
      }

生成徽章

- name: Generate badge
  run: |
    score=${{ steps.quality.outputs.score }}
    color="red"
    [ $score -ge 60 ] && color="yellow"
    [ $score -ge 80 ] && color="green"
    
    curl -o badge.svg "https://img.shields.io/badge/code%20quality-${score}%25-${color}"
    
- name: Upload badge
  uses: actions/upload-artifact@v3
  with:
    name: quality-badge
    path: badge.svg

总结

将 Claude Code 集成到 GitHub Actions 中可以显著提升代码质量和开发效率。通过自动化的代码审查、测试生成和文档更新，团队可以：

✅ 减少代码审查时间
✅ 提高测试覆盖率
✅ 保持文档同步
✅ 及早发现安全问题
✅ 确保代码质量标准

记住要合理配置工作流，避免过度使用 API 导致成本增加。建议从小规模开始，逐步扩展自动化范围。

💡 提示：定期更新 Claude Code Action 版本以获取最新功能和性能改进。