Codex CLI × GitHub Action：CI/CD連携の完全セットアップガイド
Codex CLI の GitHub Action（openai/codex-action@v1）を徹底解説。入力パラメータ・safety-strategy・sandbox・final-message 出力・allow-users / allow-bots によるトリガー制限・Agents SDK 連携を 2026 年 5 月時点の公式仕様に揃えてまとめました。
この章の要点
openai/codex-action@v1 は OpenAI 公式の GitHub Action です。prompt / prompt-file を渡すと CI ランナー上で Codex CLI が動き、最終メッセージを final-message 出力としてジョブの outputs に返します。
- 入力は
openai-api-key（必須）、promptまたはprompt-file、sandbox、safety-strategyが中心 actions/checkout@v5でチェックアウトしてから実行する前提- Windows は
safety-strategy: unsafe指定が必要（Linux/macOS はdrop-sudo推奨） allow-users/allow-bot-usersで起動を許可するアカウントを絞れる
openai/codex-action とは
GitHub Actions のステップとして Codex CLI を呼び出すためのラッパーです。openai-api-key を受け取り、Responses API へのプロキシ起動・サンドボックス設定・Codex 実行・出力ファイルの収集を一括で担います。最終メッセージは後続ステップで outputs.final-message を経由して PR コメント等に渡せます。
公式仕様の概要
公式ページには、必須入力（openai-api-key、prompt または prompt-file のいずれか）、推奨入力（safety-strategy / sandbox）、その他の任意入力、出力 final-message、対応 OS、必須 permissions、推奨ワークフロー例が記載されています。
使い方
入力パラメータ一覧
| パラメータ | 必須 | 既定値 | 説明 |
|---|---|---|---|
openai-api-key | 必須 | — | OpenAI API キー。Responses API プロキシの起動に必要 |
prompt | どちらか | — | インラインの指示テキスト |
prompt-file | どちらか | — | リポジトリ内の Markdown / テキストファイルパス |
safety-strategy | 推奨 | drop-sudo | drop-sudo / unprivileged-user / read-only / unsafe |
sandbox | 推奨 | workspace-write | read-only / workspace-write / danger-full-access |
codex-args | 任意 | — | 追加の CLI フラグ（JSON 配列または文字列） |
output-file | 任意 | — | 最終メッセージを保存するファイルパス |
output-schema / output-schema-file | 任意 | — | 構造化出力のスキーマ指定 |
model | 任意 | 未指定 | 使用モデル |
effort | 任意 | 未指定 | 推論レベル |
codex-version | 任意 | 最新 | CLI のバージョンをピン留め |
codex-home | 任意 | — | 設定ファイル・MCP の永続ディレクトリ |
codex-user | 任意 | — | safety-strategy: unprivileged-user 時に Codex を実行する UNIX ユーザー名 |
working-directory | 任意 | — | Codex を実行する作業ディレクトリ |
responses-api-endpoint | 任意 | — | Responses API エンドポイントの上書き |
allow-users | 任意 | "" | 書込権チェックをバイパスして起動を許可するユーザー名のリスト |
allow-bots | 任意 | false | github-actions[bot] の書込権チェックをバイパスするか |
allow-bot-users | 任意 | "" | バイパスを許可するボットユーザー名のリスト |
prompt と prompt-file を同時指定するとエラーになります。
出力
final-message… Codex の最終メッセージ。ジョブのoutputs経由で後続ステップに受け渡せます。
推奨ワークフロー（公式例）
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 }}prompt-file の例
<!-- .github/codex/prompts/review.md -->
# コードレビュー指示
この PR の変更内容（`git diff origin/main...HEAD`）をレビューしてください。
## チェック項目
- [ ] SQL インジェクション・XSS・CSRF の可能性がないか
- [ ] 認証・認可ロジックに問題がないか
- [ ] N+1 クエリや非効率なループがないか
- [ ] エラーハンドリングが適切か（空の catch ブロックがないか）
- [ ] テストのカバレッジが適切か
## 出力形式
問題がある場合は Markdown テーブルで出力してください：
| 深刻度 | ファイル:行 | 問題の説明 | 修正提案 |応用例：テスト失敗の自動修正
name: Auto Fix Failing Tests
on:
push:
branches:
- 'fix/**'
- 'feat/**'
jobs:
fix-tests:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- run: npm ci
- name: Run Tests (expect failure)
id: test-run
run: npm test 2>&1 | tee /tmp/test-output.txt || true
- name: Fix Failing Tests with Codex
uses: openai/codex-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
prompt: |
テスト出力 `/tmp/test-output.txt` を読み、失敗しているテストを修正してください。
- 実装コードのバグを修正する（テストは変更しない）
- 修正後に `npm test` を実行して全テストが通ることを確認する
sandbox: workspace-write
safety-strategy: drop-sudo
- name: Commit Fixes
run: |
git config --local user.email "codex-bot@users.noreply.github.com"
git config --local user.name "Codex Bot"
git diff --quiet || git commit -am "fix: Codex によるテスト失敗の自動修正"
git push応用例：Issue ラベルでの自動修正
name: Auto Fix Issue
on:
issues:
types: [labeled]
jobs:
auto-fix:
if: contains(github.event.label.name, 'codex-fix')
runs-on: ubuntu-latest
permissions:
contents: write
issues: write
pull-requests: write
steps:
- uses: actions/checkout@v5
- name: Fix with Codex
uses: openai/codex-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
allow-users: "owner1,owner2" # 信頼するユーザーだけ起動を許可
prompt: |
Issue #${{ github.event.issue.number }} の内容を分析し、TDD で修正してください。
タイトル: ${{ github.event.issue.title }}
本文:
${{ github.event.issue.body }}
指示：
1. 根本原因を特定する
2. テストを先に書いてから修正を実装する
3. 修正後にすべてのテストが通ることを確認する
sandbox: workspace-write
safety-strategy: drop-sudo
- name: Create PR
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
git config --local user.email "codex-bot@users.noreply.github.com"
git config --local user.name "Codex Bot"
BRANCH="codex-fix/issue-${{ github.event.issue.number }}"
git checkout -b $BRANCH
git add -A
git commit -m "fix: Issue #${{ github.event.issue.number }} を Codex で自動修正"
git push origin $BRANCH
gh pr create \
--title "fix: Issue #${{ github.event.issue.number }} の自動修正" \
--body "Closes #${{ github.event.issue.number }}" \
--base mainAgents SDK との併用
より細かい制御が必要な場合は、Action ではなく Python スクリプトから Agents SDK 経由で Codex を呼び出します。
# .github/scripts/codex-review.py
import asyncio
import os
from agents import Agent, Runner
from agents.mcp import MCPServerStdio
async def main():
codex_server = MCPServerStdio(
command="npx",
args=["-y", "codex", "mcp-server"],
)
reviewer = Agent(
name="pr-reviewer",
instructions="PR の差分をレビューし、品質・セキュリティ・性能の問題を指摘する",
mcp_servers=[codex_server],
)
pr_number = os.environ.get("PR_NUMBER", "")
result = await Runner.run(
reviewer,
f"PR #{pr_number} をレビューして問題点を Markdown で報告してください",
)
with open("/tmp/review.md", "w") as f:
f.write(result.final_output)
asyncio.run(main())- name: Run Codex Review Script
run: python .github/scripts/codex-review.py
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
PR_NUMBER: ${{ github.event.pull_request.number }}注意点・セキュリティ観点
API キーは必ず Secrets で管理する
secrets.OPENAI_API_KEY を openai-api-key 入力に渡します。漏洩が疑われたら即座にローテーションしてください。
safety-strategy を必ず指定する
Linux / macOS では drop-sudo（推奨）／unprivileged-user／read-only のいずれかを、Windows ランナーでは unsafe を指定します。未指定のままにすると sudo 系コマンドが意図せず通るおそれがあります。
サンドボックスは目的に合わせる
レビュー目的なら read-only、修正コミットを許す場合のみ workspace-write。danger-full-access は CI では使わないでください。
allow-users / allow-bot-users で起動権限を絞る
PR・Issue・コメント由来の起動は外部ユーザーから始められる場合があります。書込権を持たないアカウントでも Action を実行したい場合は、許可リストに明示してバイパスを限定してください。allow-bots は github-actions[bot] のチェックをバイパスするかを制御する真偽値です。
prompt のサニタイズ
PR タイトル・本文・コミットメッセージなど外部入力をそのままプロンプトに流すと、プロンプトインジェクションの入口になります。引用ブロックでくくる、命令文を分離するなど対策を施してください。
permissions を最小限に
permissions:
contents: read # 変更しないジョブはこれだけ
pull-requests: write # PR コメントを書く場合のみprompt と prompt-file を同時指定しない
同時指定はエラーになります。どちらか 1 つを選んでください。
Claude Code の GitHub Action との比較
| 観点 | openai/codex-action | Claude Code |
|---|---|---|
| 公式サポート | あり（OpenAI 公式） | 公式アクションは未提供（SDK／自作スクリプトが中心） |
| サンドボックス | OS レベル（sandbox 入力で切替） | Hooks ベース |
| セットアップ | Action 1 ステップで完結 | スクリプト実装が必要 |
| 柔軟性 | codex-args で CLI フラグ拡張 | SDK で完全カスタマイズ |
| 出力 | final-message を後続ステップで利用 | スクリプト側で実装 |