GitHub 集成与 CI/CD · Codex 橙皮书

19.1 让 AI 真正"住进"你的项目

到这一章，你已经会：

在桌面 / CLI 用 Codex 写代码
让 Codex 自动化日常任务
让多 Agent 协作

但还差一步：让 AI 直接住进 GitHub，自动 review PR、自动开 PR、自动跑测试。

这一步对开发者团队的意义巨大。它把 AI 从"我用的工具"变成"项目流程的一部分"。

19.2 三种 GitHub 集成方式

方式	触发	谁能用	复杂度
Codex Web 链接 GitHub	手动	个人	低
Codex GitHub App	PR / Issue 评论中 @	团队	中
Codex GitHub Action	YAML 配置自动	团队	中

我们一个个看。

19.3 方式一：Codex Web 链接 GitHub

最简单的玩法：在 chatgpt.com/codex 上链接你的 GitHub 账号。

设置

打开 chatgpt.com/codex
Settings → Integrations → GitHub
授权 Codex 访问你的 GitHub
选择允许 Codex 访问的仓库（可以选全部，也可以白名单）

用法

启动 Codex Web，在对话框选"From Repository"：

仓库：cassius/my-blog
分支：main

任务：帮我加一个深色模式开关，要支持 localStorage 记忆用户选择。

Codex 在云端 VM 里：

clone 你的仓库
看 AGENTS.md（如果有）
实现深色模式
跑 lint / test
推到一个新分支
给你开一个 PR

你在 GitHub 上看到 PR，review，merge。全程你没下载过仓库。

适合场景

临时小改动（不想 clone 到本地）
远程办公没带电脑（手机上也能用）
给开源项目提 PR
给同事的项目快速建议

不适合

复杂项目（云端 VM 配置可能不全）
需要本地服务的项目（数据库、本地 API）
频繁多次迭代（每次都重新 clone 慢）

19.4 方式二：Codex GitHub App

更进阶：装一个 GitHub App，让 Codex 在 PR / Issue 中可被 @ 调用。

安装

GitHub → Marketplace → 搜 "Codex"（OpenAI 官方）
选择安装到组织 / 个人
选择能访问的仓库

用法 1：PR 中调用

某 PR 提交后，你想让 Codex 看一眼：

@openai-codex 帮我 review 这个 PR，重点看安全和性能

Codex 自动:

拉取 PR 的 diff
看仓库的 AGENTS.md
做 review
在 PR 评论里留 review 结果

用法 2：Issue 中调用

某 Issue 描述了一个 bug:

@openai-codex 看下这个 issue，能不能复现并修了开个 PR？

Codex:

读 Issue
在云端 VM 里复现
找到 bug 来源
写修复
跑测试
开 PR

你只需要 review PR。

用法 3：评论中迭代

PR 评论：

@openai-codex 这部分逻辑有点绕，能不能重写得更清晰？

Codex 改完 force-push 到同一个分支。你 refresh 看 diff。

适合场景

团队协作模式
频繁的 Issue → PR 流转
有外部贡献者的开源项目（让 Codex 当一线 review）

19.5 方式三：Codex GitHub Action

最强大、最自动化的方式：在 .github/workflows/ 里配 YAML，定义"什么时候自动让 Codex 做什么"。

基础示例：自动 review PR

.github/workflows/codex-review.yml：

name: Codex PR Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: openai/codex-action@v1
        with:
          api-key: ${{ secrets.OPENAI_API_KEY }}
          mode: review
          target-branch: ${{ github.base_ref }}
          comment-on-pr: true
          focus:
            - security
            - performance
            - convention-conformance

每次有人开 PR 或 push 新 commit 到 PR：

Action 自动触发
Codex 在 ubuntu runner 上 review
在 PR 评论里留 review 结果
严重问题打 ❌，建议改进打 💡

进阶示例：自动修小 bug

.github/workflows/codex-auto-fix.yml：

name: Codex Auto Fix

on:
  issues:
    types: [labeled]

jobs:
  fix:
    if: contains(github.event.label.name, 'auto-fix-eligible')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: openai/codex-action@v1
        with:
          api-key: ${{ secrets.OPENAI_API_KEY }}
          mode: fix-issue
          issue-number: ${{ github.event.issue.number }}
          create-pr: true
          pr-base: main

      - name: Notify on PR
        uses: actions/github-script@v7
        with:
          script: |
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: ${{ github.event.issue.number }},
              body: 'PR opened by Codex! Please review.'
            });

工作流：

你给 Issue 打 auto-fix-eligible 标签
Action 触发，Codex 尝试修复
如果成功，开 PR 关联到 Issue
你 review PR
merge 后 Issue 自动关闭

进阶示例：定时整理项目

.github/workflows/codex-weekly-cleanup.yml：

name: Weekly Cleanup

on:
  schedule:
    - cron: '0 9 * * 1'  # 每周一 9:00 UTC

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: openai/codex-action@v1
        with:
          api-key: ${{ secrets.OPENAI_API_KEY }}
          mode: custom
          prompt: |
            做以下事情：
            1. 检查所有 src/ 下未引用的代码（dead code）
            2. 列出所有 TODO 注释，按文件分组
            3. 检查依赖包，列出可升级的
            4. 输出 weekly-report.md
          create-pr: true
          pr-title: "weekly: project health report"

每周一自动跑，开一个 PR 含本周项目健康报告。你 merge 或丢弃。

19.6 SSH Devbox：远程开发环境

2026 年 Codex 桌面版新增"SSH Remote"功能：让 Codex 直接连接你的远程开发服务器（aka devbox）操作。

适用场景

团队共用 dev 服务器
项目太大本地跑不动
需要稳定的环境（避免本地 macOS / Windows 差异）
异地办公

设置

桌面版菜单 → Remote → Add SSH Connection：

Host: dev.mycompany.com
Port: 22
User: cassius
Identity: ~/.ssh/dev_rsa
Workspace: /home/cassius/projects/my-app

连接后，Codex 在远程跑：

文件读写在远程
命令在远程执行
你的本地只是个"显示器"

体验跟本地 Codex 完全一致，但底层资源是远程的。

安全考虑

用 SSH key 不用密码
限制 Codex 在远程的工作目录
远程主机要有自己的备份和访问审计

19.7 一个完整的"AI 友好型 GitHub 项目"配置

如果你新建一个项目，下面是推荐的"AI 友好"完整配置：

my-project/
├── .github/
│   ├── workflows/
│   │   ├── codex-review.yml          # PR 自动 review
│   │   ├── codex-issue-triage.yml    # Issue 自动初筛
│   │   └── ci.yml                    # 常规 CI（lint + test）
│   └── ISSUE_TEMPLATE/
│       ├── bug_report.md             # 标准化 bug 报告（让 Codex 好理解）
│       └── feature_request.md        # 标准化需求
├── AGENTS.md                          # AI 通用指令
├── .codex/
│   └── skills/                       # 项目专属 Skills
├── README.md                          # 给人和 AI 看
├── ARCHITECTURE.md                    # 架构说明（AI 重点参考）
├── CONTRIBUTING.md                    # 贡献指南（含 AI 协作约定）
└── ...

Issue 模板示例

.github/ISSUE_TEMPLATE/bug_report.md：

---
name: Bug Report
about: 报告一个 bug
labels: bug
---

## 描述
（一句话）

## 复现步骤
1. 
2. 
3. 

## 预期
（应该发生什么）

## 实际
（实际发生了什么）

## 环境
- OS:
- 版本:
- 浏览器（如适用）:

## 复现日志 / 截图
（如有）

---

@openai-codex 请你看一下，能不能复现，并初步定位问题。

模板末尾的 @openai-codex 让每个新 bug 自动触发 Codex 初步分析。人来到 Issue 时，Codex 已经做了一轮分析。

19.8 安全注意事项

GitHub 集成涉及"自动改代码、自动 push"，必须谨慎：

注意 1：永远不要让 Codex push 到 main

任何 Codex 的产出走 PR，绝不直接 push 到 main / production 分支。

注意 2：CI 一定要跑通才 merge

哪怕 Codex 说"我跑过测试了"，CI 必须独立验证。

注意 3：API Key 用最小权限

OpenAI API Key 配置时，限定能访问的能力。GitHub Token 只给 PR 相关权限，不要给 Admin。

注意 4：敏感仓库不要接

含密钥、生产配置、客户数据的仓库不要用 Codex Web / GitHub App。即使数据"会被脱敏"，也存在泄露风险。

注意 5：Action 限流

GitHub Action 每月有免费额度（公共仓库无限，私有仓库 2000 分钟/月）。频繁触发可能超额，提前规划。

19.9 几个开源项目的"Codex 协作"实践

观察一些开源项目怎么用 Codex：

模式 1：Codex 作为"机器人贡献者"

它有自己的 GitHub 账号（如 codex-bot）
每个 PR 标记由 codex-bot 创建，人审 merge
在 CONTRIBUTING.md 里说明哪些任务它做、哪些它不做

模式 2：Codex 作为"机器人 reviewer"

每个 PR 提交后，Codex 留第一轮 review
人 reviewer 可以在 Codex 的基础上加内容
加快了 turnaround time

模式 3：Codex 作为"机器人 maintainer 助手"

自动 triage Issue
自动给 Issue 加 label
自动把"过期 Issue"关闭并回复
自动 sync 翻译版的 README

每个开源项目可以参考自己的工作量和风险，挑合适的模式。

19.10 个人用户的轻量玩法

不一定要团队才用 GitHub 集成。个人开发者也可以：

玩法 1：用 Codex 给自己 review

PR 模板里加：

@openai-codex 在我 merge 之前帮我看一遍，
特别是 Boundaries 里的 Always 项有没有都做到。

自己写代码自己审，还是有盲点的。让 Codex 当第二双眼。

玩法 2：定时给个人项目"健康检查"

设一个周一的 Action：

扫描项目：
1. 列出过去一周的 commit 数
2. 检查 dependencies 有没有可升级
3. 检查 TODO 注释总数
4. 给一份"项目活跃度"报告

让你客观看到自己开源项目的健康度。

玩法 3：自动同步翻译

中英双语的 README、文档：

on:
  push:
    paths: ['docs/**']

# Codex 把 docs/zh/ 的改动同步翻译到 docs/en/

写中文版，自动有英文版。

19.11 一个"未来感"的工作流

下面这个工作流不是科幻，是 2026 年顶级团队真正在用的：

PM 在 Linear 创建一个 ticket：
"用户希望能在结算页直接修改地址"
            ↓
Linear 自动同步到 GitHub Issue（带详细描述）
            ↓
Codex GitHub App 自动分析：
  - 读取 Issue
  - 看现有代码
  - 评估改动量
  - 决定是 "auto-fix-eligible" 还是 "needs-human"
  - 加对应 label
            ↓
对于 auto-fix-eligible：
  Codex Action 触发
  → 实现 → 跑测试 → 开 PR
            ↓
PR 触发：
  Codex Review Action → 留初步 review
  CI → 跑完整测试套
  人工 review → 加最终意见
            ↓
所有 check 通过 → merge
            ↓
自动部署到 staging
            ↓
另一个 Codex Action 跑 e2e 测试
            ↓
通过 → 部署 prod
            ↓
PM 在 Linear 收到通知："你的 ticket 上线了"

整个流程人工干预只有 2 处：

PM 描述需求
工程师终审 PR

中间所有"代码层面"的事，AI 接力完成。

这种工作流让小团队（3-5 人）能做出过去 20 人团队的产出。

19.12 本章小结

三种 GitHub 集成：Codex Web 链接 / GitHub App（@提及）/ Action（自动触发）
Web 链接最简单，适合个人
GitHub App 适合团队 ad-hoc 调用
Action 适合规则化的自动流程
SSH Remote 让 Codex 操作远程 devbox
AI 友好的项目配置：AGENTS.md + Skills + Issue 模板 + Action
安全：不 push main、CI 必跑、最小权限、敏感仓库不接
个人轻量玩法：自己给自己 review、健康检查、自动翻译
顶级团队的工作流：人工只在"提需求"和"终审"，中间全 AI

第六篇结束。下一篇我们看实战中的"坑"和"边界"。从第二十章 · 常见问题与避坑开始。

第十九章 GitHub 集成与 CI/CD

19.1 让 AI 真正"住进"你的项目

19.2 三种 GitHub 集成方式

19.3 方式一：Codex Web 链接 GitHub

设置

用法

适合场景

不适合

19.4 方式二：Codex GitHub App

安装

用法 1：PR 中调用

用法 2：Issue 中调用

用法 3：评论中迭代

适合场景

19.5 方式三：Codex GitHub Action

基础示例：自动 review PR

进阶示例：自动修小 bug

进阶示例：定时整理项目

19.6 SSH Devbox：远程开发环境

适用场景

设置

安全考虑

19.7 一个完整的"AI 友好型 GitHub 项目"配置

Issue 模板示例

19.8 安全注意事项

注意 1：永远不要让 Codex push 到 main

注意 2：CI 一定要跑通才 merge

注意 3：API Key 用最小权限

注意 4：敏感仓库不要接

注意 5：Action 限流

19.9 几个开源项目的"Codex 协作"实践

模式 1：Codex 作为"机器人贡献者"

模式 2：Codex 作为"机器人 reviewer"

模式 3：Codex 作为"机器人 maintainer 助手"

19.10 个人用户的轻量玩法

玩法 1：用 Codex 给自己 review

玩法 2：定时给个人项目"健康检查"

玩法 3：自动同步翻译

19.11 一个"未来感"的工作流

19.12 本章小结