自学教程

Codex GitHub 集成

Codex 教程

Codex GitHub 集成是连接 Codex 智能体与 GitHub 仓库的能力，支持仓库代码读取、Issue 任务创建、PR 自动评审、代码提交、分支管理。它包含两种接入方式：图形界面 OAuth 授权，以及基于 MCP 服务器的 CLI/自动化集成；可在桌面端、IDE扩展、命令行、GitHub Actions 流水线中使用，打通代码仓库与 Codex 自动化工作流。

一、前置条件

  1. 拥有 GitHub 账号与目标仓库读写权限。
  2. Codex 客户端（桌面 / IDE / CLI）已完成登录。
  3. 授权权限范围可选：仅公开仓库、全部仓库、手动选定仓库。

企业组织仓库，需要组织管理员批准 GitHub App 安装授权。

二、图形界面授权（桌面/网页端）

2.1 授权步骤

  1. 打开 Codex 设置页面，选择「Connect GitHub」连接 GitHub。
  2. 跳转 GitHub 授权页面，安装 ChatGPT-Codex 连接器应用。
  3. 选择授权仓库范围，确认授权。
  4. 授权完成后，Codex 可直接读取仓库代码、分支、Issue、PR 信息。

权限控制：随时可在 GitHub 应用设置中修改仓库访问范围，或断开连接。

2.2 基础能力

授权完成后，可直接在 Codex 内：

  • 读取仓库代码、目录结构、README、文档。
  • 读取 Issue，基于 Issue 创建 Codex 开发任务。
  • 读取 Pull Request 变更，执行代码评审。
  • 将 Codex 修改结果直接提交分支、创建 PR。

三、CLI 与 MCP 接入方式

在命令行环境，使用 GitHub MCP 服务完成集成，无需网页OAuth，依靠 GitHub PAT（个人访问令牌）鉴权。

3.1 配置 MCP 服务

在项目 .codex/config.toml 添加 GitHub MCP 配置：

[mcp_servers.github]
name = "github"
transport = "stdio"
command = "uvx"
args = ["mcp-server-github"]
env = {GITHUB_TOKEN = "${GITHUB_TOKEN}"}
sandbox_mode = "read-only"

令牌通过环境变量注入，禁止将 PAT 明文写入配置并提交Git。

也可以通过 CLI 快速添加 MCP 服务：

codex mcp add github --transport stdio --env GITHUB_TOKEN

3.2 环境变量配置

Linux/macOS：

export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

Windows PowerShell：

$env:GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

令牌最小权限建议：repo 范围（仓库读写），自动化评审场景可仅授予只读权限。

3.3 测试连接

/mcp info github
/mcp ping github

成功后 Codex 可调用 MCP 工具查询分支、提交记录、PR、Issue。

四、GitHub Actions 流水线集成（非交互模式）

在 CI 流水线中使用 Codex 非交互模式，实现 PR 自动评审、自动修复、更新文档。

.github/workflows/codex-review.yml 示例：

name: Codex 代码评审
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 安装 Codex
        run: npm install -g @openai/codex
      - name: Codex 评审
        env:
          CODEX_API_KEY: ${{ secrets.CODEX_API_KEY }}
        run: |
          git diff origin/main...HEAD | codex exec --quiet --approval-mode=suggest \
          "评审本次PR变更，检查安全漏洞、性能问题、代码规范，输出markdown评审报告" > review.md
      - name: 将评审结果写入PR评论
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const comment = fs.readFileSync('review.md','utf8');
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: comment
            })

五、核心自动化场景

5.1 Issue 驱动任务

Codex 读取 GitHub Issue，自动解析需求，生成代码修改方案，完成后创建分支并提交PR。

典型流程：新建Issue → Codex读取Issue描述 → 生成代码 → 创建分支 → 提交代码 → 打开PR。

5.2 PR 自动代码评审

两种触发方式：

  1. 自动触发：PR 打开或更新时，自动执行评审并写评论。
  2. 手动触发：在PR评论中输入 @codex review，指定评审方向（安全、性能、依赖）。

Codex 会对比变更意图与实际代码，运行基础检查，输出问题清单与修改建议。

5.3 分支与提交管理

支持：创建分支、查看提交记录、对比diff、提交代码、推送分支、合并前校验。

配合项目 AGENTS.md 和 rules.toml，约束修改范围，保护核心文件。

六、权限、安全与管控

  1. 最小权限原则：PAT 仅授予任务必需范围，代码评审场景优先只读权限。
  2. 令牌安全：PAT、API Key 存储在 GitHub Action Secrets / 本机环境变量，禁止提交仓库。
  3. 仓库白名单：企业可通过 Codex requirements.toml 限制可访问仓库。
  4. 操作审批：写操作（提交、创建PR）默认需要人工确认；CI流水线可配置 auto-edit，禁止直接使用 full-auto。
  5. 审计日志：所有MCP调用、仓库读写操作都会记录日志，支持事后追溯。

七、斜杆命令（Codex 通用）

# 查看当前GitHub连接状态
/github status列出仓库分支
/github branches
读取指定PR变更
/github pr show 123
从Issue创建Codex任务
/github task-from-issue 45
重载GitHub MCP配置
/mcp reload

八、集成限制

  1. GitHub 集成仅支持 GitHub 云端仓库，暂不支持私有化 GitHub Enterprise 旧版本。
  2. 读取仓库代码存在速率限制，大仓库全量索引有超时约束。
  3. 图形界面OAuth连接的Codex，和MCP方式的令牌相互独立。
  4. Computer Use 电脑操控能力无法在GitHub Actions CI环境使用。

九、最佳实践

  1. 项目配置 AGENTS.md 写明仓库模块约束，Codex提交PR时遵循项目规范。
  2. 配合钩子 pre-commit、pre-task，提交前自动执行lint、安全扫描。
  3. CI流水线统一使用 suggest 模式做评审，自动修改代码仅在隔离测试仓库启用。
  4. 定期轮换GitHub PAT，降低密钥泄露风险。
  5. 组织级使用时，统一通过GitHub App授权，不使用个人PAT作为长期凭证。

十、常见问题

Q：图形界面授权与MCP方式可以同时使用吗？
A：可以，两者独立。图形端用于交互式开发，MCP用于CLI、自动化流水线。

Q：Codex是否可以直接合并PR？
A：默认不允许，合并属于高危操作，需要人工确认；可在企业管控策略中显式开启。

Q：非交互模式codex exec是否支持GitHub MCP？
A：支持，非交互模式加载GitHub MCP，可在CI内完成PR评审、Issue读取。

Q：断开GitHub授权后，Codex还能访问本地仓库吗？
A：本地仓库文件访问不受影响，只是无法调用GitHub API读取远程仓库、PR、Issue。

十一、总结

Codex GitHub 集成打通了代码仓库与AI智能体的开发流水线，提供网页OAuth和MCP服务两种接入方案。支持Issue生成任务、PR自动评审、分支提交、GitHub Actions自动化。

结合AGENTS.md、rules.toml、钩子、非交互模式，能够实现从需求Issue到代码评审的全链路自动化。在使用时坚持最小权限，妥善保管访问令牌，可安全落地团队级AI开发工作流。

标签：

0 条笔记