openai/codex-action
GitHub: openai/codex-action
OpenAI 官方的 GitHub Action，用于在 CI 工作流中安全运行 Codex CLI 以实现 AI 驱动的代码审查与自动化任务。
Stars: 1065 | Forks: 131
# Codex GitHub Action
从 GitHub Actions 工作流中运行 [Codex](https://github.com/openai/codex#codex-exec)，同时对 Codex 可用的权限保持严格控制。此 Action 负责安装 Codex CLI，并为其配置一个指向 [Responses API](https://platform.openai.com/docs/api-reference/responses) 的安全代理。
用户必须提供其选定提供商的 API 密钥（例如，[`OPENAI_API_KEY`](https://platform.openai.com/api-keys) 或 `AZURE_OPENAI_API_KEY` [如果使用 Azure 托管的 OpenAI 模型](#azure)）作为 [GitHub Actions secret](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets) 才能使用此 Action。
## 示例：创建你自己的 Pull Request Bot
虽然 Codex 云端提供了今天就可以使用的[强大代码审查工具](https://developers.openai.com/codex/cloud/code-review)，但如果你想对体验有更多控制权，这里有一个示例，展示如何使用 `openai/codex-action` 构建你自己的代码审查工作流。
在以下示例中，我们定义了一个在用户创建 Pull Request 时触发的工作流，它会：
- 创建仓库的浅克隆。
- 确保 PR 的 `base` 和 `head` ref 在本地可用。
- 使用包含 PR 特定详细信息的 `prompt` 运行 Codex。
- 获取 Codex 的输出并将其作为评论发布到 PR 上。
请参阅 [`security.md`](./docs/security.md) 获取有关安全使用 `openai/codex-action` 的提示。
```
name: Perform a code review when a pull request is created.
on:
pull_request:
types: [opened]
jobs:
codex:
runs-on: ubuntu-latest
permissions:
contents: read
outputs:
final_message: ${{ steps.run_codex.outputs.final-message }}
steps:
- uses: actions/checkout@v5
with:
# Explicitly check out the PR's merge commit.
ref: refs/pull/${{ github.event.pull_request.number }}/merge
persist-credentials: false
- name: Pre-fetch base and head refs for the PR
env:
PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
PR_NUMBER: ${{ github.event.pull_request.number }}
run: |
# Pass GitHub expressions through env and quote shell expansions.
git fetch --no-tags origin \
"$PR_BASE_REF" \
"+refs/pull/$PR_NUMBER/head"
# If you want Codex to build and run code, install any dependencies that
# need to be downloaded before the "Run Codex" step because Codex's
# default sandbox disables network access.
- name: Run Codex
id: run_codex
uses: openai/codex-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
prompt: |
This is PR #${{ github.event.pull_request.number }} for ${{ github.repository }}.
Review ONLY the changes introduced by the PR, so consider:
git log --oneline ${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}
Suggest any improvements, potential bugs, or issues.
Be concise and specific in your feedback.
Pull request title and body:
----
${{ github.event.pull_request.title }}
${{ github.event.pull_request.body }}
post_feedback:
runs-on: ubuntu-latest
needs: codex
if: needs.codex.outputs.final_message != ''
permissions:
issues: write
pull-requests: write
steps:
- name: Report Codex feedback
uses: actions/github-script@v7
env:
CODEX_FINAL_MESSAGE: ${{ needs.codex.outputs.final_message }}
with:
github-token: ${{ github.token }}
script: |
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.payload.pull_request.number,
body: process.env.CODEX_FINAL_MESSAGE,
});
```
## 输入
| 名称 | 描述 | 默认值 |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `openai-api-key` | 使用 OpenAI（默认）时用于启动 Responses API 代理的密钥。请将其存储在 `secrets` 中。 | `""` |
| `responses-api-endpoint` | 可选的 Responses API 端点覆盖，例如 `https://example.openai.azure.com/openai/v1/responses`。留空则使用代理的默认值。 | `""` |
| `prompt` | 内联 prompt 文本。提供此项或 `prompt-file`。 | `""` |
| `prompt-file` | 包含 prompt 的文件路径（相对于仓库根目录）。提供此项或 `prompt`。 | `""` |
| `output-file` | 写入最终 Codex 消息的文件。留空则跳过写入文件。 | `""` |
| `working-directory` | 传递给 `codex exec --cd` 的目录。默认为仓库根目录。 | `""` |
| `sandbox` | Codex 的沙盒模式。可选值为 `workspace-write`（默认）、`read-only` 或 `danger-full-access`。 | `""` |
| `codex-version` | 要安装的 `@openai/codex` 版本。 | `""` |
| `codex-args` | 转发给 `codex exec` 的额外参数。接受 JSON 数组 (`["--flag", "value"]`) 或 shell 风格的字符串。 | `""` |
| `output-schema` | 写入临时文件并传递给 `codex exec --output-schema` 的内联 schema 内容。与 `output-schema-file` 互斥。 | `""` |
| `output-schema-file` | 转发给 `codex exec --output-schema` 的 schema 文件。留空则跳过传递该选项。 | `""` |
| `model` | agent 应使用的模型。留空则让 Codex 选择其默认值。 | `""` |
| `effort` | agent 应使用的推理力度。留空则让 Codex 选择其默认值。 | `""` |
| `codex-home` | 用作 Codex CLI 主目录（config/cache）的目录。留空则使用 CLI 的默认值。 | `""` |
| `safety-strategy` | 控制 Action 如何限制 Codex 权限。参见[安全策略](#safety-strategy)。 | `drop-sudo` |
| `codex-user` | 当 `safety-strategy` 为 `unprivileged-user` 时，运行 Codex 的用户名。 | `""` |
| `allow-users` | 除了对仓库有写入权限的用户之外，可以触发此 Action 的 GitHub 用户名列表。 | `""` |
| `allow-bots` | 允许受信任的 GitHub bot 账户 (`github-actions[bot]`) 触发的运行绕过写入权限检查。 | `false` |
| `allow-bot-users` | 可以绕过写入权限检查的 GitHub bot 用户名列表。不支持 `*`；请明确列出受信任的 bot。 | `""` |
## 安全策略
`safety-strategy` 输入决定了 Codex 在 runner 上获得多少访问权限。选择正确的选项至关重要，尤其是当存在敏感 secret（如你的 OpenAI API 密钥）时。
有关此主题的重要细节，请参阅安全页面上的[保护你的 `OPENAI_API_KEY`](./docs/security.md#protecting-your-openai_api_key)。
- **`drop-sudo`（默认）** — 在 Linux 和 macOS runner 上，此 Action 会在调用 Codex 之前撤销默认用户的 `sudo` 成员资格。然后 Codex 将以该用户身份运行，没有超级用户权限。此更改将在 job 的其余部分持续有效，因此后续步骤无法使用 `sudo`。这通常是 GitHub 托管的 runner 上最安全的选择。
- **`unprivileged-user`** — 以通过 `codex-user` 提供的用户身份运行 Codex。如果你管理自己的 runner 并且拥有预先创建的非特权账户，请使用此选项。确保该用户可以读取仓库检出以及 Codex 需要的任何文件。有关如何在 `ubuntu-latest` 上配置此类账户的示例，请参见 [`unprivileged-user.yml`](./examples/unprivileged-user.yml)。
- **`read-only`** — 在只读沙盒中执行 Codex。Codex 可以查看文件，但不能更改文件系统或直接访问网络。OpenAI API 密钥仍通过代理传递，因此如果 Codex 能够访问进程内存，它就可以读取该密钥。
- **`unsafe`** — 不降低权限。Codex 以默认的 `runner` 用户身份运行（通常拥有 `sudo` 权限）。仅在你完全信任 prompt 时才使用此选项。在 Windows runner 上，这是唯一受支持的选项，如果提供其他选项，Action 将会失败。
### 操作系统支持
- **Windows**：GitHub 托管的 Windows runner 缺乏受支持的沙盒。请设置 `safety-strategy: unsafe`。Action 会对此进行验证，否则将提前退出。
- **Linux/macOS**：支持 `safety-strategy` 的所有选项。再次提醒，如果你选择 `drop-sudo`，请记住 `job` 中依赖 `sudo` 的后续步骤将会失败。如果你确实需要在 `openai/codex-action` 运行之后运行需要 `sudo` 的代码，一种选择是将 `openai/codex-action` 的输出通过管道传递给新主机上的全新 `job`，并从那里继续你的工作流。
- **GitHub 托管的 Linux runner**：此 Action 在设置期间会启用非特权用户命名空间，并在存在时清除 Ubuntu 的 AppArmor 限制。这避免了在较新的托管镜像上出现的 `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` 失败，包括那些使用此 Action 一次来引导 Codex 然后在后续步骤中调用 `codex` 的工作流。自托管的 Linux runner 仍需提前配置等效的内核支持。
## 输出
| 名称 | 描述 |
| --------------- | --------------------------------------- |
| `final-message` | `codex exec` 返回的最终消息。 |
正如我们在上面的示例中所见，我们获取了 `run_codex` 步骤的 `final-message` 输出，并将其作为工作流中 `codex` job 的输出：
```
jobs:
codex:
# ...
outputs:
final_message: ${{ steps.run_codex.outputs.final-message }}
```
## 额外提示
- 在 `actions/checkout@v5` 之后运行此 Action，以便 Codex 可以访问你的仓库内容。
- 要使用非默认的 Responses 端点（例如 Azure OpenAI），请将 `responses-api-endpoint` 设置为提供商的 URL，同时保持 `openai-api-key` 已填充；代理仍会将 `Authorization: Bearer ` 发送到上游。
- 如果你希望 Codex 访问少量特权功能，请考虑运行一个能够执行这些操作的本地 MCP server，并配置 Codex 使用它。
- 如果你需要对 CLI 调用进行更多控制，请通过 `codex-args` 传递标志，或在 `codex-home` 中创建一个 `config.toml`。
- 一旦 `openai/codex-action` 使用 `openai-api-key` 运行一次，你也可以在 job 的后续脚本中调用 `codex`。（在这种情况下，你可以从 Action 中省略 `prompt` 和 `prompt-file`。）
## Azure
要将 Action 配置为使用 Azure 上托管的 OpenAI 模型，请密切注意以下几点：
- `responses-api-endpoint` 必须设置为 Codex 将向其 `POST` Responses API 请求的完整 URL（包括任何必需的查询参数）。对于 Azure，这可能类似于 `https://YOUR_PROJECT_NAME.openai.azure.com/openai/v1/responses`。请注意，[与在 Codex 中自定义模型提供商时不同](https://github.com/openai/codex/blob/main/docs/config.md#azure-model-provider-example)，你必须根据需要自行在 URL 中包含 `v1/responses` 后缀。
- `openai-api-key` 输入必须是有效的密钥，该密钥能够在向你的 Responses API 端点发出 `POST` 请求时用于 `Authorization: Bearer ` 请求头。（在使用 Codex CLI 设置自定义提供商时，[`env_key`](https://github.com/openai/codex/blob/main/docs/config.md#azure-model-provider-example) 的值也是如此。）
最终，你配置好的 Action 可能类似于以下内容：
```
- name: Start Codex proxy
uses: openai/codex-action@v1
with:
openai-api-key: ${{ secrets.AZURE_OPENAI_API_KEY }}
responses-api-endpoint: "https://bolinfest-7804-resource.cognitiveservices.azure.com/openai/v1/responses"
prompt: "Debug all the things."
```
## 版本历史记录
有关详细信息，请参阅 [`CHANGELOG`](./CHANGELOG.md)。
## 许可证
该项目基于 [Apache License 2.0](./LICENSE) 授权。
标签：AI代码辅助, GitHub Action, MITM代理, OpenAI Codex, SOC Prime, 代码审查, 开发工具, 网络调试, 自动化, 自动化攻击