深度实战系列 [GitHub 集成深度解析（本文）] | 渐进式规划深度解析

GitHub 是现代软件开发的协作中枢。Codex 和 Claude Code 都提供了丰富的 GitHub 集成能力，但集成方式、深度和适用场景差异显著。本文基于官方文档和社区实践，逐项拆解两种工具的 GitHub 集成路径。

第一部分：Codex GitHub 集成

Codex 提供了四种 GitHub 集成路径，覆盖 PR 生命周期的主要环节。

路径 1：@codex review——PR 代码审查

触发方式：在 PR 评论中 @ 提及 Codex。

@codex review

Codex 收到请求后的完整流程：

模式选择——在 Codex Code Review 设置 中配置：

自定义审查规则——在 AGENTS.md 中添加 ## Review guidelines 段：

## Review guidelines

- Don't log PII.
- Verify that authentication middleware wraps every route.
- Check for N+1 queries in database access code.
- SQL queries must use parameterized statements.
- API responses must include request ID header for tracing.

这些规则成为 Codex 每次审查的固定检查项。规则越具体，审查越精准。

定向审查——针对特定关注点：

@codex review for security regressions
@codex review focus on error handling in the payment flow
@codex review only check the new API endpoints

定向审查比全量审查更快、结果更聚焦。对于大型 PR，建议先全量扫一遍，再对关键模块做定向审查。

社区实践——多轮审查工作流

第 1 轮：@codex review                         → 全量快速扫描
第 2 轮：人工审阅 P0/P1 问题，修复明确 bug
第 3 轮：@codex review for security regressions → 聚焦安全检查
第 4 轮：人工确认 + 合并

这种方式综合了 AI 的速度和人的判断力。社区反馈显示，4 轮审查后合并的 PR，生产事故率降低了约 40%（基于 Hacker News 和 r/programming 的用户报告）。

路径 2：@codex fix——自动修复 PR 问题

审查发现 P1 问题后，直接在 PR 评论中请求修复：

@codex fix the P1 issue
@codex fix the CI failures
@codex fix all P1 issues in this PR

Codex 启动 Cloud Task，以 PR 为上下文：

1. 拉取 PR 分支到 Cloud 环境
2. 分析 review 中指出的问题
3. 生成修复代码
4. 运行相关测试确认修复有效
5. 推送修复到 PR 分支

完整端到端流程：

注意事项：

• @codex fix 仅修复 P1 问题，P0 问题建议人工修复（涉及业务逻辑理解）
• 修复后建议再跑一轮 @codex review 确认没有引入新问题
• 如果 CI 失败原因是测试用例本身有问题，@codex fix 可能会误改测试——需要人工确认

路径 3：Security 插件——安全扫描 + 一键 PR

Codex Security 插件扫描已连接的 GitHub 仓库，对发现的安全漏洞可直接从发现页面创建修复 PR。

命令：

$codex-security:security-diff-scan    # 日常 diff 扫描（快）
$codex-security:security-scan         # 全仓库深度扫描（慢但彻底）

扫描覆盖范围：

一键修复流程：扫描发现 → 点击漏洞详情 → 查看 Codex 建议的修复 → 点击 "Create PR" → 自动创建包含修复的 PR 到 GitHub。

路径 4：Automations + GitHub 插件——持续监控

通过 Codex Automations 配合 GitHub 插件，实现定时 PR 监控：

自动化名称：PR Health Check
调度：*/30 * * * *（每 30 分钟）
模式：Standalone（独立运行）
Worktree：是

监控内容：

1. 通过 GitHub 插件获取所有 open PR
2. 检查每个 PR 的 CI 状态
3. 如果 CI 失败，分析日志并尝试推送修复
4. 如果有新的 review 评论需要回复，生成回复草稿
5. 汇总到 Triage 收件箱

配置建议：

第二部分：Claude Code GitHub 集成

Claude Code 的 GitHub 集成更深度，包括原生 GitHub App、多 Agent 审查、和 GitHub Actions CI 集成。

路径 1：GitHub App——自动 PR 审查

Claude Code 的 GitHub App 是独立的审查服务，运行在 Anthropic 基础设施上。

安装：

claude
/install-github-app

按照提示在 GitHub 组织中安装 Claude GitHub App。需要的权限：

审查机制——五层流水线：

严重程度标签：

反馈机制：每个 Review 评论自带 👍👎 按钮。Anthropic 收集反馈用于持续优化审查器质量。这是 Claude Code 独有的能力——用户反馈直接回流到模型训练。

触发方式对比：

路径 2：/code-review --comment——CLI 到 GitHub inline

在本地 CLI 中审查后，直接把发现发布到 GitHub PR 上：

/code-review effort=high --comment

Claude Code 分析本地 diff，将每条发现定位到 PR 的具体文件和行号，以 inline comment 的形式发布。

三种审查方式的对比：

路径 3：GitHub Actions——CI 流水线集成

Claude Code 提供官方 GitHub Action，可在 CI 流水线中运行：

# .github/workflows/claude-review.yml
name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 需要完整 git 历史以计算 diff
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

关键用例——自动修复 CI 失败：

name: Claude Code CI Fixer
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  auto-fix:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            The CI pipeline failed. Analyze the failure logs and fix the code.
            After fixing, push the changes to the current branch.
            Do NOT fix: flaky tests, environment issues, infra problems.

CI 集成的高级模式：

路径 4：claude --from-pr——从 PR 恢复会话

claude --from-pr 234

直接从 PR 编号启动 Claude Code 会话，自动加载：

• PR 的 diff
• PR 的讨论历史
• 关联的 Issue 上下文
• CI 运行日志

适合需要深度分析某个复杂 PR 时快速进入状态。相比手动打开 PR 再贴 diff 给 AI，这个命令节省了 5-10 分钟的上下文准备时间。

第三部分：混合集成策略

两个工具的 GitHub 集成不是互斥的——它们可以互补。

策略 1：双工具协同 PR 审查

Codex 负责速度和 CI 修复，Claude Code 负责深度发现——两者互补，覆盖不同层次的问题。

策略 2：按仓库类型选型

策略 3：成本优化

GitHub 集成的成本是持续性的——每个 PR 都会产生 token 消耗。

成本分层方案：

建议：

• 日常 PR：L1 + L2（总成本 ~$0.12/PR）
• 核心模块 PR：L1 + L3（总成本 ~$2.02/PR）
• 安全敏感 PR：L1 + L4（总成本 ~$5.02/PR）

第四部分：安全权限最佳实践

GitHub App 权限最小化

安装任何 GitHub App 时，遵循最小权限原则：

# 推荐权限设置
permissions:
  contents: read        # 只在需要推送修复时设为 write
  pull-requests: write  # 发布审查评论需要
  issues: read          # 只在需要响应 Issue 时设为 write
  metadata: read        # 所有 App 都需要

权限审计清单：

• 每个 write 权限是否有明确的业务需求？
• 是否可以用 read + 人工确认替代 write？
• 仓库机密文件（.env, 密钥）是否在 .gitignore 中？
• CI secret 是否正确配置且定期轮换？

敏感分支保护

对 main / release 分支设置保护规则：

分支保护 → main
  ✅ Require a pull request before merging
  ✅ Require approvals (≥1)
  ✅ Require status checks to pass before merging
  ✅ Require conversation resolution before merging
  ✅ Do not allow bypassing the above settings

AI 工具的自动推送（@codex fix、Claude 自动修复）应该推送到 PR 分支而非 main。

第五部分：故障排查

常见问题

Debug 模式

Codex：

@codex review --verbose

输出审查过程的详细日志，包括读取了哪些文件、应用了哪些规则。

Claude Code：

/code-review effort=high --verbose

显示每个 Agent 的发现过程，便于人工判断审查质量。

总结

GitHub 集成不是"选哪个"的问题，而是"如何组合"的问题。Codex 的自动化和快速反馈 + Claude Code 的深度审查和多 Agent 交叉验证，构成了完整的质量保障体系。

回到系列导航：实战教程系列总览

实操清单

• 在 AGENTS.md 中编写 ## Review guidelines 段，定制审查规则
• 实践一次 @codex review + 人工审阅 + @codex fix 的完整流程
• 安装 Claude Code GitHub App，为团队仓库启用自动 PR 审查
• 配置 .github/workflows/claude-review.yml CI 流水线
• 安装 Codex Security 插件，连接 GitHub 仓库，运行首次全仓扫描
• 配置 Codex Automation 做 PR 状态监控（推荐每 30 分钟）
• 实践一次双工具协同审查：Codex 快速扫描 + Claude Code 深度审查
• 为敏感分支（main/release）设置分支保护规则
• 审查 GitHub App 权限设置，确认最小权限原则
• 建立团队的成本分层方案（L1-L4），根据 PR 重要性选配