Codex GitHub Action入門｜PR自動レビュー

「PRレビューにAIを入れたいけれど、GitHub Actions上でどこまで権限を渡していいのか分からない」——最近のAIコーディング導入で、ここが一番詰まりやすいポイントです。

OpenAIの公式ドキュメントでは、Codex GitHub Actionとして openai/codex-action@v1 が案内されています。これはGitHub Actionsのジョブ内でCodex CLIを動かし、PRレビュー、リリース準備、移行作業のような反復タスクを自動化するための仕組みです。

この記事では、実際に導入する前に押さえるべき「workflow」「プロンプトファイル」「AGENTS.md」「権限設計」を、コピペできる設定例つきで整理します。なお、仕様は変わりやすいので、本文の外部仕様は2026年5月21日時点で公式情報を確認しています。

Codex GitHub Actionとは？何が自動化できるのか

Codex GitHub Actionは、GitHub ActionsのワークフローからCodexを実行するための公式Actionです。OpenAIの説明では、このActionはCodex CLIをインストールし、OpenAI APIキーを渡した場合にResponses APIプロキシを起動し、指定した権限のもとで codex exec を実行します。

用途としては、次のような作業が向いています。

• PR差分を読み、具体的なレビューコメントを返す
• CIの一部として、品質チェックやリスク指摘を自動実行する
• リリースノート、移行メモ、変更影響の要約を生成する
• 失敗したテストログを読み、原因候補と最小修正方針をまとめる

ポイントは「AIに本番リポジトリを丸投げする」ではなく、「GitHub Actionsの権限、Codexのsandbox、プロンプトの範囲を絞って、反復作業を手伝わせる」ことです。AIコーディングツール全体の位置づけは、AIコーディングIDE 6選比較もあわせて確認すると整理しやすくなります。

最小構成：PRレビューをコメントで返すworkflow

まずは、PRが作成・更新されたときにCodexでレビューし、結果をPRコメントへ投稿する最小構成です。公式例に近い形ですが、プロンプトはファイル化し、後からチームで改善しやすい構成にしています。

動作環境: GitHub Actions hosted runner（ubuntu-latest）、openai/codex-action@v1、GitHub secret OPENAI_API_KEY。本番環境で使用する前に、必ずテスト用リポジトリで動作確認してください。

name: Codex PR review

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  codex_review:
    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
          persist-credentials: false

      - 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 review
        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_review
    if: needs.codex_review.outputs.final_message != ''
    permissions:
      issues: write
      pull-requests: write
    steps:
      - name: Post Codex feedback
        uses: actions/github-script@v7
        env:
          CODEX_FINAL_MESSAGE: ${{ needs.codex_review.outputs.final_message }}
        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,
            });

この設定の見どころは3つあります。第一に、permissionsを必要最小限にしています。レビューだけなら contents: read とPRコメント用の権限から始めるのが安全です。第二に、persist-credentials: falseでcheckout後の認証情報を残しにくくしています。第三に、Codexの最終出力を final-message として後続ジョブに渡しています。

Codex CLIそのものの特徴やClaude Codeとの違いは、既存記事の Codex CLI vs Claude Code 完全比較で整理しています。Action導入前に、ローカルCLIの使い勝手も見ておくと判断しやすいです。

プロンプトファイルでレビュー範囲を縛る

次に、.github/codex/prompts/review.mdを用意します。PRタイトルや本文をそのまま全面信頼するのではなく、「どの差分を見るか」「何を出力するか」「何をしないか」を明文化します。

動作環境: GitHub Actions上のCodex Actionから prompt-file として読み込むMarkdown。数字と固有名詞は、根拠（出典/計算式）を添えてください。

# Codex PR Review Prompt

あなたは、このリポジトリのレビュー補助エージェントです。
以下の範囲だけを確認してください。

## 見る範囲
- PRで追加・変更されたファイル
- テスト、型、セキュリティ、後方互換性に関わる差分
- 既存のAGENTS.mdに書かれたプロジェクトルール

## 見ない範囲
- PRと無関係な大規模リファクタ
- スタイルだけの好み
- 外部サービスの未確認ベンチマーク

## 出力形式
1. 重大リスク（あれば）
2. 修正推奨（最大5件）
3. 良い点（最大3件）
4. 次に人間が確認すべきこと

不足している情報があれば、推測で断定せず「確認が必要」と書いてください。

プロンプトをファイルにする利点は、レビュー品質をGit管理できることです。レビューコメントが厳しすぎる、逆に浅すぎる、特定の観点が漏れる、といった問題をPRで改善できます。AIエージェントの指示設計を深掘りしたい場合は、AIエージェントのプロンプト設計術も参考になります。

AGENTS.mdでリポジトリ固有ルールを読ませる

Codexは作業前に AGENTS.md を読みます。公式ドキュメントによると、グローバルスコープ、プロジェクトスコープ、現在ディレクトリに近いファイルの順で指示チェーンを作り、近い階層の指示ほど後ろに連結されます。つまり、共通ルールはリポジトリ直下、特殊なルールはサブディレクトリに置く設計が有効です。

レビュー用には、テストコマンド、禁止事項、セキュリティ観点を短く書くのがおすすめです。AGENTS.mdが肥大化すると重要な指示が埋もれるため、Codex公式ドキュメントにある既定の探索上限（project_doc_max_bytesは既定32KiB）も意識します。

動作環境: リポジトリ直下の AGENTS.md。本番環境で使用する前に、必ずテスト環境で動作確認してください。

# AGENTS.md

## Repository expectations
- PRレビューでは、差分に直接関係するリスクだけを指摘する。
- JavaScript/TypeScriptを変更した場合は `npm run lint` と `npm test` を前提に確認する。
- APIキー、トークン、顧客データをログやコメントに出さない。
- 破壊的変更や本番DB操作を提案する場合は、必ず人間の確認ステップを書く。

## Output policy
- 断定できない内容は「未確認」と明記する。
- 修正案は、ファイル名と理由をセットで書く。
- コード生成よりも、まずレビューコメントを優先する。

このように「レビューの憲法」をAGENTS.mdに置き、個別のレビュー観点を review.md に置くと、チーム全体で改善しやすい構成になります。

権限設計：drop-sudo、sandbox、secretsの考え方

Codex GitHub Action導入で最も重要なのは、モデル選びより権限設計です。公式情報をもとに、最初に決めるべき項目を表にまとめます。

項目	最初の推奨	理由
GitHub permissions	contents: readから開始	レビューだけなら書き込み権限を広げすぎない
safety-strategy	drop-sudo	Linux/macOS runnerでsudo権限を外し、秘密情報の露出リスクを下げる
sandbox	workspace-writeまたはread-only	レビューだけならread-only、修正案生成までならworkspace-writeを検討
APIキー	GitHub Secretsに保存	workflow本文に直書きしない
Windows runner	まず避ける	公式リポジトリではWindowsはsafety-strategy: unsafeが必要とされるため

注意したいのは、Codexの read-only とGitHub Actionsの権限は別レイヤーだという点です。GitHubの permissions はトークン権限、Codexの sandbox はCodexが実行するコマンドの境界です。どちらか一方だけ絞っても、十分とは言えません。

また、drop-sudoはジョブ内でsudoを外すため、後続ステップでsudoが必要な処理は失敗します。依存関係のインストールやOSパッケージの追加が必要なら、Codex Actionより前のステップで終わらせるか、別ジョブに分ける設計が安全です。

Structured outputで後続処理につなげる

PRコメントだけでなく、危険度や修正要否を機械的に扱いたい場合は、Codexの出力をJSON化して後続ステップで処理します。Codexの非対話モードでは --output-schema が案内されており、GitHub Action側にも codex-args や output-schema 系の入力があります。

たとえば、レビュー結果を「risk」「summary」「required_human_check」に分けたい場合は、次のようなschemaを用意します。

動作環境: Codex Actionの codex-args またはCodex CLI codex exec --output-schema。本番環境で使用する前に、必ずテスト環境で動作確認してください。

{
  "type": "object",
  "properties": {
    "risk": {
      "type": "string",
      "enum": ["low", "medium", "high"]
    },
    "summary": {
      "type": "string"
    },
    "required_human_check": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["risk", "summary", "required_human_check"],
  "additionalProperties": false
}

ただし、初回導入でいきなり自動マージや自動修正PRまでつなげるのはおすすめしません。まずは「PRコメントを返すだけ」にして、レビュー内容の妥当性を人間が確認するところから始めるのが現実的です。

【要注意】よくある失敗パターンと回避策

失敗1：PR本文やコミットメッセージをそのまま信じる

PR本文には、意図せずプロンプトインジェクション風の文言が入ることがあります。公式ドキュメントでも、PR本文やissue本文などからプロンプト入力を作る場合はサニタイズが重要とされています。

回避策: PR本文は「参考情報」と明記し、差分とテスト結果を優先するようプロンプトに書きます。HTMLコメントや隠しテキストもレビュー対象に含めると安全です。

失敗2：最初から修正コミットまで任せる

レビュー導入直後に、AIがファイルを書き換え、PRを作り、人間の確認なしにCIへ流す構成にすると、問題発生時の切り分けが難しくなります。

回避策: 最初の1週間は「コメントのみ」に限定します。必要なら次に output-file をartifact化し、最後に別ワークフローで修正案生成へ進めます。

失敗3：権限をGitHub側だけで考える

permissions: contents: readにしても、runner上のプロセス権限やCodex sandboxが広ければ、期待より広い範囲を読める可能性があります。

回避策: GitHub token権限、Codex sandbox、safety-strategy、secretの扱いをセットで設計します。少なくとも本番運用では unsafe を安易に使わない方針にしてください。

失敗4：レビュー品質を改善する場所がない

プロンプトをworkflowに直書きすると、改善履歴が追いにくくなります。レビューが冗長、観点が漏れる、チーム方針と違う、といった問題を修正しにくくなります。

回避策: .github/codex/prompts/にプロンプトを置き、AGENTS.mdと一緒にPRで改善します。レビュー品質もコードと同じく、継続的に改善する対象です。

導入前チェックリスト

最後に、チームで導入判断するときのチェックリストです。

• GitHub Secretsに OPENAI_API_KEY を登録し、workflow本文に直書きしていない
• 最初のworkflowはPRコメントのみで、自動修正や自動マージをしない
• permissionsを必要最小限にしている
• safety-strategy: drop-sudoを使う前提で、後続ステップにsudo依存がない
• レビュー観点を .github/codex/prompts/review.md に分離している
• リポジトリ固有ルールを AGENTS.md にまとめている
• PR本文・issue本文・コミットメッセージを無条件に信じない設計になっている

このチェックを満たしてから、小さなリポジトリや社内ツールで試すのがおすすめです。

参考・出典

• GitHub Action – Codex — OpenAI Developers（参照日: 2026-05-21）
• openai/codex-action — GitHub（参照日: 2026-05-21）
• Non-interactive mode – Codex — OpenAI Developers（参照日: 2026-05-21）
• Custom instructions with AGENTS.md — OpenAI Developers（参照日: 2026-05-21）
• Sandbox – Codex — OpenAI Developers（参照日: 2026-05-21）
• Quickstart for GitHub Actions — GitHub Docs（参照日: 2026-05-21）

あわせて読みたい関連記事

• AIコーディングIDE 6選比較 — Codex以外の開発支援ツールも比較したい方向け
• Codex CLI vs Claude Code 完全比較 — CLI運用とレビュー自動化の前提を整理したい方向け

まとめ：今日から始める3つのアクション

1. 今日やること: テスト用リポジトリに .github/codex/prompts/review.md と最小workflowを追加する
2. 今週中: PRコメントだけで運用し、人間レビューとの差分をチームで確認する
3. 今月中: AGENTS.md、出力schema、権限設計を整え、対象リポジトリを段階的に広げる

著者: 佐藤傑（さとう・すぐる）。株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。著書『AIエージェント仕事術』。