---
title: "用 GitHub Action 跑 Codex"
description: "基于官方 Codex GitHub Action 教程，讲清 openai/codex-action@v1 适合什么 CI/CD 任务、权限怎么给、结果怎么验收。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

Codex GitHub Action，也就是 `openai/codex-action@v1`，是在 GitHub Actions 里运行 Codex 的官方入口。它安装 Codex CLI，在你提供 API key 时启动 Responses API proxy，并按指定权限运行 `codex exec`。

> [!WARNING]
> GitHub Action 不是免审自动合并器。第一版只做只读 PR review；自动修复和推送必须放到更后面，并保留人工 review。

<Cards>
  <Card title="GitHub Action" href="https://developers.openai.com/codex/github-action">
    官方 Codex GitHub Action 文档。
  </Card>
  <Card title="Non-interactive mode" href="/docs/codex/official/01-products/28-non-interactive">
    Action 本质上是在 workflow 里运行 `codex exec`。
  </Card>
  <Card title="CI/CD auth" href="/docs/codex/official/06-team-integration/44-cicd-auth">
    先处理 API key、GitHub token 和 fork PR 风险。
  </Card>
</Cards>

## 什么时候用

```mermaid
flowchart LR
    Event["GitHub event"] --> Workflow["workflow job"]
    Workflow --> Action["openai/codex-action"]
    Action --> Exec["codex exec"]
    Exec --> Output["final message / artifact / patch"]
    Output --> Review["PR review / human approval"]
```

适合：

- 在 PR 上自动生成 Codex review。
- 把 Codex 检查放进 CI pipeline。
- 不想自己安装和管理 Codex CLI。
- 需要把最终 Codex message 传给后续 GitHub steps。
- 任务已经可以用 `codex exec` 清楚描述。

不适合：

- prompt 还没写清。
- 不知道应该给 read-only 还是 workspace-write。
- 让来自任意 fork 的输入直接驱动 Codex。
- 没准备好保护 OpenAI key 和 GitHub token。
- 希望 Codex 无限制自动改主分支。

## Prompt 放哪里

短任务可以用 inline `prompt`。

长期维护的任务放进 prompt file，例如：

```text
.github/codex/prompts/review.md
```

`prompt` 和 `prompt-file` 二选一。新手推荐 prompt file，因为它能被团队 review、版本管理和复用。CI prompt 也是代码资产，不应该藏在无人维护的 workflow 片段里。

## 权限怎么给

权限要分三层看：

- GitHub job permissions。
- Codex sandbox。
- runner safety strategy。

只读 review 通常从 `contents: read` 起步。要回写 PR comment 时，再给 `pull-requests: write`。

Codex sandbox 也先收紧：

- read-only：审查、总结、风险报告。
- workspace-write：生成 patch 或修改工作区文件。
- danger-full-access：不作为默认 CI 路线。

官方 Action 默认 safety strategy 是 `drop-sudo`。Windows runner 需要特殊处理，不应作为新手第一版路线。

## 触发条件

不要让任何人都能触发带 secret 的 Codex job。来自 PR、issue、commit message 的内容都要当成不可信输入。

尤其注意：

- fork PR。
- 外部贡献者。
- 自动评论触发。
- workflow dispatch 输入。
- issue body 和 PR description 里的 prompt injection。

如果工作流会使用 `OPENAI_API_KEY` 或 GitHub token，触发条件必须保守。

## 输出怎么用

Action 会提供最终 Codex message。你可以把它交给后续 step：

- 发 PR comment。
- 上传 artifact。
- 写入报告。
- 作为 job output 给后续任务消费。

如果只需要人读，保存 final message 就够。如果要程序解析，底层 `codex exec` 应使用结构化输出，例如通过 schema 固定字段。

不要一开始就做“自动应用 + 自动提交 + 自动评论”。先保存输出、人工看，再逐步自动化。

## 稳妥落地顺序

第一版：只读 PR review。Codex 只输出风险点，不改文件。

第二版：把结果发成 PR comment。GitHub token 只给评论所需权限。

第三版：在受控分支上生成 patch，并复跑测试。

第四版：只有测试通过时，才开自动修复 PR，仍然由人 review。

这个顺序能让团队先建立信任，再扩大自动化范围。

## 常见坑

- 把 Action 当成能替代 CI 的质量系统。
- prompt 太宽，输出泛泛意见。
- workflow、GitHub token、Codex sandbox 权限都太大。
- secret 进入日志、artifact 或 prompt 输出。
- 同时设置 `prompt` 和 `prompt-file`。
- 没有 checkout 代码，Codex 读不到 repository contents。
- 让不可信用户触发带写权限的 job。

## 验收清单

- Action 运行前已经 checkout 正确 diff。
- 能说明 GitHub job permissions、Codex sandbox、safety strategy。
- 日志里能看到 Codex 最终输出，但看不到 OpenAI key、auth 文件和私有 token。
- 失败时能定位 prompt、API key、proxy、sudo strategy、文件权限或触发者权限。
- 同一个 PR 重跑能得到稳定格式的结果。
- 自动修复必须生成可 review 的 PR，不直接改主分支。

## 官方资料

- [Codex GitHub Action](https://developers.openai.com/codex/github-action)
- [Non-interactive mode](https://developers.openai.com/codex/noninteractive)
- [openai/codex-action repository](https://github.com/openai/codex-action)
