---
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="/zh-Hant/docs/codex/official/01-products/28-non-interactive">
    Action 本質上是在 workflow 裡執行 `codex exec`。
  </Card>
  <Card title="CI/CD auth" href="/zh-Hant/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)
