TL;DR:
- Codex CLI を GitHub Actions に組み込むと、PR単位で自動コード修正・テスト修復・リリースノート生成が動く
- サンドボックス実行(ネットワーク無効・ディレクトリ限定)により意図しない副作用を防ぎながら自動化できる
- 3つのワークフロー(コード修正・リリースノート・テスト修復)を独立YAML化して段階的に導入するのが安全
はじめに
CIが赤のまま放置される、リリースノートの作成を忘れる、Lintエラーが毎回同じパターンで出る——こうした繰り返し作業はCodexに任せられる。
OpenAI Codex CLI(公式リポジトリ)は2025年4月にリリースされたオープンソースのコーディングエージェントで、codex run コマンドを使うとGitHub Actions等のCI/CD環境から直接呼び出せる。o3モデルによる推論特化の分析力をパイプライン上で活用できる点が最大の特徴だ。
本記事では以下の3つのパイプラインを具体的なYAMLサンプルとともに解説する:
- PR自動コード修正: Lint/型エラーをCIがPushで自動修正してcommit
- リリースノート自動生成: マージ後にCHANGELOGをAIが生成してPR
- テスト自動修復: CIがfailしたテストをCodexが解析して修正
Codexと他のAIコーディングツールの使い分けについては Codex vs Claude Code 使い分け2026 も参照してほしい。
前提条件と環境設定
必要なもの
| 項目 | 詳細 |
|---|---|
| Codex CLI バージョン | 0.1.x以降(確認日: 2026-06-01) |
| 対応OS | macOS / Linux(GitHub ActionsのUbuntu runner対応) |
| 必要な権限 | OPENAI_API_KEY(環境変数)、リポジトリのwrite権限 |
| GitHub Actions | contents: write、pull-requests: write パーミッション |
インストールと動作確認
# Codex CLI インストール(npm経由)
npm install -g @openai/codex
# バージョン確認
codex --version
# 動作テスト(サンドボックスモードで実行)
codex run --sandbox "echo hello from codex"
--sandbox フラグを付けると、ネットワークアクセスが無効化され、指定ディレクトリ外への書き込みがブロックされる。CI環境では必ず --sandbox を使うのが原則だ(公式ドキュメント:セキュリティモデル)。
GitHub Actionsのシークレット設定
# GitHub CLIでシークレットを設定
gh secret set OPENAI_API_KEY --body "$OPENAI_API_KEY"
リポジトリの Settings → Secrets and variables → Actions から手動設定も可能。
パイプライン1: PR自動コード修正
概要
PRがopenされたタイミングでCodexがLintエラー・型エラーを検出し、自動修正commitをPushする。レビュアーは修正済みのコードをレビューするだけでよくなる。
GitHub Actions YAML(完全サンプル)
# .github/workflows/codex-auto-fix.yml
name: Codex Auto Fix
on:
pull_request:
types: [opened, synchronize]
branches:
- main
- develop
permissions:
contents: write
pull-requests: write
jobs:
auto-fix:
runs-on: ubuntu-latest
# 自分のcommitによるPRはスキップ(無限ループ防止)
if: github.actor != 'github-actions[bot]'
steps:
- name: Checkout
uses: actions/checkout@v4
with:
ref: ${{ github.head_ref }}
token: ${{ secrets.GITHUB_TOKEN }}
fetch-depth: 0
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Install Codex CLI
run: npm install -g @openai/codex
- name: Run lint check
id: lint
run: npm run lint 2>&1 | tee lint-output.txt || true
- name: Run type check
id: typecheck
run: npm run type-check 2>&1 | tee typecheck-output.txt || true
- name: Auto fix with Codex
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
run: |
# lint/型エラーが存在する場合のみ修正を実行
LINT_OUTPUT=$(cat lint-output.txt)
TYPE_OUTPUT=$(cat typecheck-output.txt)
if [ -n "$LINT_OUTPUT" ] || [ -n "$TYPE_OUTPUT" ]; then
codex run --sandbox \
--model o4-mini \
--approval-mode auto-edit \
"以下のlintエラーと型エラーを修正してください。
コードのロジックは変えず、エラーを解消することだけに集中してください。
Lintエラー:
$LINT_OUTPUT
型エラー:
$TYPE_OUTPUT"
else
echo "エラーなし。修正不要。"
fi
- name: Check for changes
id: check-changes
run: |
if git diff --quiet; then
echo "changed=false" >> $GITHUB_OUTPUT
else
echo "changed=true" >> $GITHUB_OUTPUT
fi
- name: Commit and push fixes
if: steps.check-changes.outputs.changed == 'true'
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add -A
git commit -m "fix: Codexによる自動Lint/型エラー修正 [skip ci]"
git push origin ${{ github.head_ref }}
- name: Comment on PR
if: steps.check-changes.outputs.changed == 'true'
uses: actions/github-script@v7
with:
script: |
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: '🤖 Codexが自動修正を行いました。差分を確認してください。'
})
設計上の注意点
--approval-mode auto-edit の使い方: このフラグを付けると、Codexが確認なしにファイルを編集する。ロジック変更を防ぐため、プロンプトで「コードのロジックは変えず」と明示的に指示することが重要だ(経験則)。
無限ループ防止: if: github.actor != 'github-actions[bot]' でbotのPushによる再トリガーを防ぐ。[skip ci] のコミットメッセージも同様の効果がある。
--model o4-mini: Lintエラー修正は推論の深さより速さが重要なため、o3の代わりにo4-miniを使う。コスト削減にもなる(経験則)。
パイプライン2: リリースノート自動生成
概要
mainブランチへのマージ後、Codexがコミット履歴を分析してCHANGELOGを生成し、自動でPRを作成する。
GitHub Actions YAML(完全サンプル)
# .github/workflows/codex-release-notes.yml
name: Codex Release Notes Generator
on:
push:
branches:
- main
workflow_dispatch:
inputs:
from_tag:
description: '起点タグ(省略時は直近のタグ)'
required: false
permissions:
contents: write
pull-requests: write
jobs:
generate-release-notes:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0 # 全履歴が必要
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Codex CLI
run: npm install -g @openai/codex
- name: Get commit range
id: commit-range
run: |
# 直近のタグを取得
LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
if [ -z "$LATEST_TAG" ]; then
# タグがない場合は最初のコミットから
FROM_COMMIT=$(git rev-list --max-parents=0 HEAD)
else
FROM_COMMIT=$LATEST_TAG
fi
echo "from=$FROM_COMMIT" >> $GITHUB_OUTPUT
echo "to=HEAD" >> $GITHUB_OUTPUT
# コミット一覧を生成
git log $FROM_COMMIT..HEAD \
--pretty=format:"%h %s (%an)" \
--no-merges > commit-list.txt
cat commit-list.txt
- name: Generate release notes with Codex
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
run: |
COMMITS=$(cat commit-list.txt)
CURRENT_DATE=$(date +%Y-%m-%d)
codex run --sandbox \
--model o3 \
--approval-mode full-auto \
"以下のコミット履歴を分析して、CHANGELOG.mdにリリースノートを追記してください。
フォーマット:
## [Unreleased] - $CURRENT_DATE
### Added
- 新機能の説明
### Fixed
- バグ修正の説明
### Changed
- 変更の説明
### Breaking Changes
- 破壊的変更(あれば)
コミット履歴:
$COMMITS
注意:
- 技術的な変更を人間が理解できる言葉に変換する
- 複数のコミットが同じ機能に関係する場合は1行にまとめる
- CHANGELOGファイルがない場合は新規作成する"
- name: Create pull request
uses: peter-evans/create-pull-request@v6
with:
token: ${{ secrets.GITHUB_TOKEN }}
commit-message: "docs: Codexによるリリースノート自動生成"
branch: "chore/release-notes-${{ github.run_number }}"
title: "docs: リリースノート更新(自動生成)"
body: |
## 概要
Codex CLIによってコミット履歴からリリースノートを自動生成しました。
## 確認事項
- [ ] 内容が正確か確認
- [ ] 破壊的変更の記載漏れがないか確認
- [ ] バージョン番号が正しいか確認
labels: |
documentation
automated
Conventional Commitsとの組み合わせ
Conventional Commits仕様(feat:, fix:, chore:等のプレフィックス)に従ってコミットメッセージを書いていると、Codexがより正確なカテゴリ分類を行える。Conventional Commitsを強制するために commitlint を併用するのが実用的だ(経験則)。
パイプライン3: テスト自動修復
概要
CIでテストがfailしたとき、Codexがエラーログを解析してテストコードまたは実装コードを修正するPRを自動作成する。
GitHub Actions YAML(完全サンプル)
# .github/workflows/codex-test-repair.yml
name: Codex Test Repair
on:
workflow_run:
workflows: ["CI"]
types: [completed]
permissions:
contents: write
pull-requests: write
jobs:
repair-tests:
runs-on: ubuntu-latest
# テストがfailした場合のみ実行
if: ${{ github.event.workflow_run.conclusion == 'failure' }}
steps:
- name: Checkout
uses: actions/checkout@v4
with:
ref: ${{ github.event.workflow_run.head_branch }}
fetch-depth: 0
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Install Codex CLI
run: npm install -g @openai/codex
- name: Collect test failure logs
id: collect-logs
run: |
# テストを再実行してエラーログを収集
npm test 2>&1 | tee test-output.txt || true
# 失敗したテストファイルを特定
grep -E "FAIL|● " test-output.txt | head -50 > failed-tests.txt
cat failed-tests.txt
echo "has_failures=$([ -s failed-tests.txt ] && echo true || echo false)" >> $GITHUB_OUTPUT
- name: Repair tests with Codex
if: steps.collect-logs.outputs.has_failures == 'true'
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
run: |
FAILURES=$(cat failed-tests.txt)
FULL_OUTPUT=$(cat test-output.txt | tail -200)
codex run --sandbox \
--model o3 \
--approval-mode auto-edit \
"以下のテスト失敗を修正してください。
判断基準:
1. テストが実装の意図を正しく反映している場合 → 実装コードを修正
2. テストの期待値が仕様変更により古くなっている場合 → テストコードを修正
3. どちらか判断できない場合 → コメントを追加して修正を提案するが、実際の変更は行わない
失敗したテスト:
$FAILURES
詳細なエラーログ:
$FULL_OUTPUT"
- name: Create fix PR
if: steps.collect-logs.outputs.has_failures == 'true'
uses: peter-evans/create-pull-request@v6
with:
token: ${{ secrets.GITHUB_TOKEN }}
commit-message: "fix: Codexによるテスト自動修復"
branch: "fix/codex-test-repair-${{ github.run_number }}"
title: "fix: テスト失敗の自動修復(Codex)"
body: |
## 概要
CIのテスト失敗を検知し、Codex CLIが自動修復しました。
## 必ず確認すること
- [ ] 修正内容がテストの意図と一致しているか
- [ ] 実装コードの変更が仕様に沿っているか
- [ ] 副作用のある変更がないか
> ⚠️ 自動生成のPRです。マージ前に必ず人間がレビューしてください。
labels: |
bug
automated
needs-review
テスト修復の限界と人間レビューの役割
Codexによるテスト修復が有効なのは、エラーメッセージが明確なケース(型不一致、スナップショット不一致等)に限られる。以下のケースは人間のレビューが必須だ(経験則):
- ビジネスロジックの変更を伴う修復
- 複数ファイルにまたがる依存関係の変更
- 「テストを削除」という形での修復提案
このパイプラインのPRには必ず needs-review ラベルを付けて、CODEOWNERS設定でシニアエンジニアのレビューを必須化することを推奨する。
3パイプラインの統合設計
実行順序とゲート設計
PR open
↓
[codex-auto-fix] → Lint/型エラーを自動修正
↓ (修正commitをPush)
[CI本体] → テスト実行
↓ PASS
mainブランチへマージ
↓
[codex-release-notes] → CHANGELOGを自動生成・PR作成
CIがfailした場合:
[CI本体] → テスト失敗
↓
[codex-test-repair] → テスト修復PRを作成
↓ (人間がレビュー・マージ)
[CI本体] → 再実行
コスト最適化
| パイプライン | 推奨モデル | 理由 |
|---|---|---|
| 自動コード修正 | o4-mini | 速度・コスト優先。推論の深さ不要 |
| リリースノート生成 | o3 | 文章品質・要約精度が重要 |
| テスト修復 | o3 | 複雑な推論が必要なケースがある |
OpenAI APIの料金については 公式料金ページ を参照。o3とo4-miniの価格差は大きいため、タスクの複雑さに応じたモデル選択が総コストに影響する。
セキュリティ設計
すべてのパイプラインで以下を遵守する:
--sandboxフラグは必須: ネットワーク無効化・ディレクトリ限定OPENAI_API_KEYはGitHub Secretsで管理: コードに直書きしない- bot commitには
[skip ci]を付ける: 無限ループ防止 - PRレビューを人間が最終承認: 特にテスト修復は必須
既存CI/CDへの段階的導入
フェーズ1: リリースノート生成から始める(リスク最小)
コードを変更しないため、最もリスクが低い。まずこのワークフローから導入して、Codexの動作に慣れる。
フェーズ2: PR自動コード修正(低〜中リスク)
Lintエラーに限定して自動修正を適用する。プロンプトで「ロジックは変えない」を明示し、差分を必ずレビューする習慣をチームに定着させる。
フェーズ3: テスト自動修復(中リスク)
最もリスクが高いため、needs-review ラベルとCODEOWNERS必須レビューを設定してから導入する。
マルチエージェントパターンとして各パイプラインを組み合わせる際は マルチエージェント開発パターン も参考になる。
運用チェックリスト
導入前チェック
-
OPENAI_API_KEYをGitHub Secretsに設定済み - GitHub Actionsのパーミッション(
contents: write,pull-requests: write)を確認 - Codex CLIのバージョンを固定(
package.jsonのdevDependenciesに追加) - サンドボックスモードの動作確認(
codex run --sandbox "ls")
導入後の定期確認
- Codexによる自動修正の差分を週次でサンプリングレビュー
- OpenAI APIの利用コストを月次確認(使用量ダッシュボード)
- 誤修正のパターンをログに残し、プロンプトを改善
AIを活用した開発計画立案との連携については AI駆動の開発計画 を参照。コードレビューをさらに強化したい場合は AIコードレビュー実践ガイド も合わせて読んでほしい。
よくある失敗パターンと対処法
パターン1: Codexが意図しないロジック変更を行う
症状: Lintエラーを修正する際、コードのロジックまで書き換えられた
原因: プロンプトが曖昧で、Codexが最適化と誤解した
対処: プロンプトに「コードのロジックは一切変えないこと」を明示。--approval-mode を auto-edit から suggest に変えてドライランで確認する
パターン2: 無限ループでワークフローが連続実行される
症状: botのcommitがトリガーになり、ワークフローが無限に実行される
原因: if: github.actor != 'github-actions[bot]' の設定漏れ
対処: YAMLの jobs.<job>.if に必ず追加。コミットメッセージに [skip ci] も追加する
パターン3: サンドボックスエラーでワークフローが落ちる
症状: codex run --sandbox でファイルアクセスエラーが出る
原因: サンドボックスがアクセスできないパスにファイルがある
対処: --sandbox オプションに --allowed-paths で作業ディレクトリを明示指定する(公式オプション一覧)
FAQ
Q. Codex CLIはプライベートリポジトリで使えますか?
はい。OPENAI_API_KEY があれば、パブリック・プライベートを問わず使えます。コードはOpenAI APIに送信されるため、機密コードを含むリポジトリではデータプライバシーポリシーを確認の上、Enterprise契約(データ保持なし)を検討してください。
Q. o3とo4-miniはどちらを選ぶべきですか?
単純なLint修正は o4-mini、複雑な推論が必要なリリースノート生成・テスト修復は o3 を推奨します。コストはo3の方が高い(公式料金 で最新値を確認)ため、タスクの複雑さで使い分けるのが経済的です。
Q. 自動修正がマージされた後に問題が発覚した場合はどうしますか?
通常のgit操作(git revert)で戻せます。Codexのcommitは通常のcommitと変わりません。[skip ci] タグが付いているため、revertしてもCIが再トリガーされます。根本対処としては、プロンプトを改善して同じ誤修正が再発しないようにします。
Q. GitHub Actions以外のCI(CircleCI、GitLab CI等)でも使えますか?
はい。codex run はCLIコマンドなので、Node.jsが動く環境であればどのCI/CDでも使えます。本記事のYAMLをベースに、各CI固有の構文(CircleCIの run: ステップ等)に書き換えてください。
Q. 実行コストの目安はどのくらいですか?
PR1件あたりのLint修正(o4-mini)は概ね0.01〜0.05ドル程度(経験則)。リリースノート生成(o3)はコミット数によるが10〜50コミットで0.1〜0.5ドル程度(経験則)。詳細は OpenAI使用量ダッシュボード でモニタリングしてください。
👉 シリーズ全体像: Codex vs Claude Code 使い分け2026
まとめ
CodexをCI/CDに組み込むことで、繰り返し型の手作業をパイプラインに吸収できる。導入のポイントは:
- 段階的に導入する: リリースノート→自動修正→テスト修復の順でリスクを管理
--sandboxは絶対に外さない: セキュリティの最低ライン- 人間レビューを最終ゲートに: 特にテスト修復は自動マージしない
- プロンプトは具体的に: 「ロジックは変えない」等の制約を明示する
次のステップとして、CodexをAIエージェントとして組み合わせる マルチエージェント開発パターン や、AIレビューを開発フロー全体に広げる AIコードレビュー実践ガイド も参照してほしい。
References
- OpenAI Codex CLI 公式リポジトリ — インストール・オプション・セキュリティモデル
- OpenAI API 料金ページ — o3/o4-mini の最新料金
- GitHub Actions 公式ドキュメント — ワークフロー構文リファレンス
- peter-evans/create-pull-request アクション — PR自動作成アクション
- Conventional Commits 仕様 — コミットメッセージ規約
- OpenAI データプライバシーポリシー — 企業利用時の確認事項
