主题
Codex GitHub Action
当你需要 Codex 参与 CI/CD 作业、应用补丁或直接从 GitHub Actions 工作流发布审查时，使用 Codex GitHub Action (openai/codex-action@v1)。
该 Action 安装 Codex CLI，在你提供 API 密钥时启动 Responses API 代理，然后在你指定的权限下运行 codex exec。
使用场景
- 自动修复失败的 CI 作业
- 自动化代码审查
- 应用补丁到 PR
- 在 CI/CD 管道中运行 Codex 任务
先决条件
- GitHub 仓库
- OpenAI API 密钥（存储为 GitHub Secret）
- GitHub Actions 工作流
示例工作流
以下示例工作流审查新的 pull request，捕获 Codex 的响应，并将其发布回 PR。
yaml
name: Codex pull request review
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
codex:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
outputs:
final_message: ${{ steps.run_codex.outputs.final-message }}
steps:
- uses: actions/checkout@v5
with:
ref: refs/pull/${{ github.event.pull_request.number }}/merge
- name: Pre-fetch base and head refs
run: |
git fetch --no-tags origin \
${{ github.event.pull_request.base.ref }} \
+refs/pull/${{ github.event.pull_request.number }}/head
- name: Run Codex
id: run_codex
uses: openai/codex-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
prompt-file: .github/codex/prompts/review.md
output-file: codex-output.md
safety-strategy: drop-sudo
sandbox: workspace-write
post_feedback:
runs-on: ubuntu-latest
needs: codex
if: needs.codex.outputs.final_message != ''
steps:
- name: Post Codex feedback
uses: actions/github-script@v7
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,
});
env:
CODEX_FINAL_MESSAGE: ${{ needs.codex.outputs.final_message }}将 .github/codex/prompts/review.md 替换为你自己的提示文件，或使用 prompt 输入进行内联文本。示例还将最终 Codex 消息写入 codex-output.md 以供后续检查或工件上传。
配置 Codex Exec
通过设置映射到 codex exec 选项的 action 输入来微调 Codex 的运行方式：
| 输入 | 说明 |
|---|---|
openai-api-key | OpenAI API 密钥（必需） |
prompt | 内联提示文本 |
prompt-file | 提示文件路径 |
output-file | 输出文件路径 |
sandbox | 沙箱模式：read-only、workspace-write、danger-full-access |
codex-args | 传递给 codex exec 的额外参数 |
管理权限
Codex 在 GitHub 托管的运行器上继承了大量访问权限，除非你限制它。使用这些输入来控制暴露：
| 输入 | 说明 |
|---|---|
safety-strategy | 安全策略：drop-sudo（推荐）、none |
sandbox | 沙箱级别限制文件系统和网络访问 |
安全策略
drop-sudo— 移除 sudo 权限，防止提权none— 不应用额外安全限制
捕获输出
Action 通过 final-message 输出发出最后的 Codex 消息。将其映射到作业输出（如上所示）或在后续步骤中直接处理。
当你需要结构化数据时，通过 codex-args 传递 --output-schema 来强制 JSON 格式。
结合 output-file 和上传工件功能，如果你更喜欢从运行器收集完整的对话记录。
安全检查清单
- ✅ 将 API 密钥存储为 GitHub Secret
- ✅ 使用
safety-strategy: drop-sudo - ✅ 限制
permissions到最小必需 - ✅ 审查 Codex 输出后再合并更改
- ✅ 考虑在 fork PR 上禁用 Action
自动修复 CI 失败
一个常见用例是在 CI 失败时自动修复。示例工作流：
yaml
name: Auto-fix CI failures
on:
workflow_run:
workflows: ["CI"]
types: [completed]
jobs:
auto-fix:
runs-on: ubuntu-latest
if: ${{ github.event.workflow_run.conclusion == 'failure' }}
permissions:
contents: write
pull-requests: write
steps:
- uses: actions/checkout@v5
with:
ref: ${{ github.event.workflow_run.head_branch }}
- name: Run Codex to fix
uses: openai/codex-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
prompt: "Fix the CI failure based on the error logs"
sandbox: workspace-write
safety-strategy: drop-sudo
- name: Create PR with fixes
uses: peter-evans/create-pull-request@v5
with:
title: "fix: Auto-fix CI failure"
body: "This PR was automatically created by Codex to fix CI failures."
branch: auto-fix/${{ github.event.workflow_run.head_branch }}故障排除
Action 超时
- 增加
timeout-minutes在作业级别 - 使用更简洁的提示
- 考虑拆分为多个步骤
权限错误
- 检查
permissions配置 - 确保 API 密钥有效
- 验证仓库设置允许 Actions
输出为空
- 检查提示是否清晰
- 验证
output-file路径 - 查看 Action 日志获取详细信息