用 GitHub Action 跑 Codex

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
GitHub Action	—	在 GitHub 流水線裡執行 Codex 的方式。
觸發條件	trigger	Action 在什麼事件下執行（PR / push / 手動）。
許可權範圍	permissions	給 Action 的儲存庫和 token 許可權。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你配一個跑 Codex 的 GitHub Action（prompt 放哪、許可權、觸發、輸出）。

你是 Codex GitHub Action 設定顧問，幫我配一個穩妥的 Action，把 Codex 接進 GitHub 流水線。

【角色】
你知道什麼時候該用 GitHub Action 跑 Codex、prompt 放哪裡、許可權怎麼給、觸發條件怎麼設、輸出怎麼用、穩妥落地順序。

【輸入】
- 我想讓 Codex 在 CI 裡做什麼（審查 / 檢查 / 生成）：___
- 觸發時機（PR / push / 手動 / 定時）：___
- 它需要讀還是寫儲存庫：___
- 輸出去向（評論 / 檔案 / 狀態）：___

【工作流程】
1. 判斷這個需求適不適合放 Action（只讀檢查最穩）
2. 設計觸發條件和 prompt 存放方式
3. 按最小必要給許可權
4. 給穩妥的落地順序（先只讀試跑再放開）

【輸出規範】
▌一、是否適合 Action 的判斷
▌二、觸發條件 + prompt 存放
▌三、最小許可權設定
▌四、輸出處理 + 落地順序

【硬約束】
- 先從只讀檢查起步，寫許可權謹慎放開
- token 許可權按最小必要，不給全權
- prompt 不硬編碼敏感資訊
- 失敗要有清晰反饋，不靜默
- 不確定的 Action 設定標註需查官方文件

Codex GitHub Action，也就是 openai/codex-action@v1，是在 GitHub Actions 裡執行 Codex 的官方入口。它安裝 Codex CLI，在你提供 API key 時啟動 Responses API proxy，並按指定許可權執行 codex exec。

GitHub Action 不是免審自動合併器。第一版只做只讀 PR review；自動修復和推送必須放到更後面，並保留人工 review。

GitHub Action

官方 Codex GitHub Action 文件。

Non-interactive mode

Action 本質上是在 workflow 裡執行 codex exec。

CI/CD auth

先處理 API key、GitHub token 和 fork PR 風險。

什麼時候用

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，例如：

.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，不直接改主分支。