在 CI/CD 中維護認證

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
auth.json	認證檔案	快取登入憑據的檔案，放進 CI 有洩露風險。
CI 認證	CI auth	在流水線裡讓 Codex 透過認證的兩條路線。
短期憑據	ephemeral token	用完即失效的憑據，比長期 key 更安全。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你在 CI/CD 裡配好 Codex 認證，既能跑通又不洩露憑據。

你是 Codex CI/CD 認證設定顧問，幫我在流水線裡配好認證，避免憑據洩露和常見坑。

【角色】
你清楚 CI 認證的兩條路線、怎麼選、auth.json 直接進 CI 的風險、常見坑，以及出問題怎麼判斷。

【輸入】
- 我的 CI 平臺（GitHub Actions / GitLab / 其它）：___
- 任務是隻讀檢查還是會寫改動：___
- 現有的憑據形式（ChatGPT 登入 / API key）：___
- 安全合規要求：___

【工作流程】
1. 按平臺和任務性質選認證路線
2. 說明為什麼不要把 auth.json 直接塞進 CI
3. 給憑據注入和最小許可權做法
4. 給出問題時的排查清單

【輸出規範】
▌一、推薦認證路線 + 理由
▌二、憑據注入方式（secret / 短期憑據）
▌三、最小許可權設定
▌四、常見坑 + 排查清單

【硬約束】
- 憑據走 CI secret，絕不明文寫進儲存庫或記錄
- 優先短期 / 最小許可權憑據，避免長期全權 key
- 寫改動的 CI 任務要有審批或限制
- 不確定的認證機制標註需查官方文件
- 給的設定要能直接用，不空泛

Codex 自動化認證的預設答案是 API key。只有當你確實需要讓 workflow 以你的 Codex account 身份執行時，才使用 ChatGPT-managed auth 的高階方案。

~/.codex/auth.json 包含 access tokens，按密碼處理。不要 commit、貼工單、發聊天、進記錄、進 artifact，也不要用於 public 或 open-source repository。

CI/CD auth

官方高階 auth.json 維護方案。

Non-interactive mode

大多數 CI 任務直接用 API key 跑 codex exec。

GitHub Action

GitHub Actions 場景優先走官方 action 和 secret。

兩條路線

flowchart LR
    CI["CI/CD job"] --> API["API key secret"]
    CI --> Auth["ChatGPT-managed auth.json"]
    API --> Default["default route"]
    Auth --> Advanced["trusted private runner only"]

API key 路線：把 CODEX_API_KEY 或 action 需要的 OpenAI key 放進 CI secret，由 job 注入。它更容易發放、輪換和撤銷，是大多數自動化預設選擇。

ChatGPT-managed auth 路線：先在可信機器上 codex login 生成 auth.json，把它放到可信 runner，讓 Codex 在執行中使用內建 refresh flow，並把更新後的 auth.json 留給下一次 run。

第二條路線的核心不是“自己呼叫 refresh API”。官方推薦的是執行 Codex，讓 Codex 自己重新整理，然後持久化重新整理後的檔案。

怎麼選擇

用 API key：

普通 CI/CD。
公開儲存庫或開源儲存庫。
GitHub Actions、GitLab CI、Jenkins 等常規自動化。
只需要跑 codex exec 或 Codex GitHub Action。
希望憑據容易輪換。

考慮 ChatGPT-managed auth：

必須以 Codex account 身份執行，而不是 API key。
runner 是可信私有基礎設施。
遠端 runner 不能執行 browser login。
能在 runs 之間儲存重新整理後的 auth.json。
同一份 auth.json 不會被併發 job 或多臺機器同時使用。

有一項不滿足，就不要用 auth.json 方案。

auth.json 風險

auth.json 不適合多機共享。一個 runner 或一個序列 workflow stream 使用一份獨立 copy。併發使用會導致 token refresh 互相覆蓋，最終出現 401 或無法重新整理。

Self-hosted runner 最適合高階方案，因為它能在 jobs 之間保留 CODEX_HOME。第一次缺檔案時 seed auth.json，後續不要每次用原始 secret 覆蓋它。

Ephemeral runner 也能做，但必須實現 restore、run、persist 閉環：

從安全儲存恢復目前 auth.json。
執行 Codex。
把本次可能重新整理過的檔案寫回安全儲存。

關鍵點是寫回重新整理後的檔案，不是寫回原始 seed。

常見坑

在公開儲存庫裡用 ChatGPT-managed auth。
把 auth.json 當普通設定檔。
每次 run 都覆蓋原檔案，丟掉重新整理後的 token。
多個併發 job 共享同一份 auth.json。
自己手寫 OAuth refresh 請求。
refresh token 被 revoke、expired 或被別的機器旋轉後，沒有重新 seed。
把完整 auth.json 上傳 artifact。

出問題怎麼判斷

出現 401 時，先判斷：

runner 是否能讀取目前 auth.json。
它是否被舊 secret 覆蓋。
是否有併發 job 使用同一份檔案。
secure storage 的 restore / persist 是否成功。
persist 是否寫回本次執行後的檔案。

仍然失敗時，不要手寫 refresh 請求。回到可信機器重新 codex login，生成新的 auth.json，重新 seed runner。

驗收清單

API key 只存在 CI secret 中，記錄沒有列印。
job 能執行 codex exec，失敗時能輪換 key。
ChatGPT-managed auth 只在可信私有 runner 使用。
auth.json 許可權收緊，沒有進入儲存庫、記錄和 artifact。
每次 run 後能保留重新整理後的檔案。
同一份 auth.json 不會被兩個 job 同時使用。
一旦懷疑洩露，立即重新登入、替換 secret、撤銷舊憑據。