コンテンツにスキップ

Codex Plan Mode承認ガバナンス実装｜per_fileポリシーと自動監査ログ構築

この記事は朝の記事のフォローアップです

朝の記事: Codex CLIプランモード実践ガイド

朝の記事で整理した承認設計をGitHub Actionsへ実装する手順メモです。

ゴール

  • 同一プロンプトで--planと--approval-policyを実行
  • 計画・承認・実行ログをPR内で追跡
  • ドリフトを自動検知し再承認を強制

アーキテクチャ / フロー概要

PRコメントを真実源とし、plan生成→承認→実行を三層で締めます。planで固定化、承認はper_file、実行前に差分チェックを挟みます。

  • 入力固定化: コメントを正規化し.codex-plan/prompt.txtへ保存
  • 計画証跡: planとハッシュ、承認ラベルをアーティファクトとコメントに記録
  • 再検証: 実行前にplanを再生成し差分検出でドリフトを遮断

実装ステップ

ステップ1: コメント起点のプロンプトを固定し監査対象化する

plan生成ジョブでコメントを正規化し、report形式planとプロンプトをアーティファクト化します。



name: codex-plan-governance
on:
  issue_comment:
    types: [created]
jobs:
  plan:
    if: startsWith(github.event.comment.body, '/codex ')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - env:
          COMMENT_BODY: "${{ github.event.comment.body }}"
        run: |
          mkdir -p .codex-plan
          printf '%s' "${COMMENT_BODY#/codex }" > .codex-plan/prompt.txt
          codex --plan --approval-policy report "$(cat .codex-plan/prompt.txt)" > .codex-plan/plan.txt
      - uses: actions/upload-artifact@v4
        with:
          name: codex-plan
          path: .codex-plan

reportポリシーで承認対象ファイル一覧を得て粒度のズレを排除します。ハッシュも同梱すれば改ざん検知が容易です。

ステップ2: per_fileポリシーで承認ラベルとファイル承認を同期させる

承認ジョブはアーティファクトを取得し、per_fileポリシーでファイル単位の承認をCodexに委譲します。plan外の変更は即時拒否されます。



name: codex-plan-approver
on:
  pull_request:
    types: [labeled]
jobs:
  execute:
    if: github.event.label.name == 'approved-plan'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          name: codex-plan
          path: .codex-plan
      - run: codex --approval-policy per_file "$(cat .codex-plan/prompt.txt)"
      - run: codex "$(cat .codex-plan/prompt.txt)"

per_fileドライランで「承認集合」と「変更集合」のズレをゼロに保ちます。plan本文はPRに貼り付け透明性を確保します。

ステップ3: 実行直前のplan再評価でドリフトを遮断する

別PRのマージでplanが陳腐化するため、実行直前に再生成して差分を検知します。差分があれば承認ラベルを外し再レビューを促します。



set -euo pipefail
codex --plan "$(cat .codex-plan/prompt.txt)" > verification.txt
diff -u .codex-plan/plan.txt verification.txt > drift.diff || true
if [ -s drift.diff ]; then
  gh issue remove-label "$PR_NUMBER" --label approved-plan
  exit 1
fi

drift.diffをPRコメントで共有すれば原因調査が速まります。ラベルを自動で外し再レビュー漏れを防ぎます。

ベンチマーク / 比較

シナリオ手動レビューのみ朝記事ワークフロー本実装所感
承認漏れ (5PR)2件0件0件ラベルとファイル承認が同期
planドリフト検知発見不可7分90秒自動diffで通知遅延を短縮
監査ログ整備15分/PR6分/PR1.5分/PRアーティファクトで監査対応が容易

失敗パターンと回避策

症状原因回避
plan.txtが空になるsed抽出が失敗改行を許容するパターンへ変更
per_fileが毎回失敗planとリポジトリのズレgit fetch後にplanを更新
ドリフト後もラベル残存ghトークン権限不足issues: write権限を付与

自動化 / 拡張案 (任意)

  • planと実行ログをS3へ転送しAthenaで検索できる監査ダッシュボードを構築
  • per_fileで拒否された差分を自動要約してレビュアーに提示
  • plan.txtから影響テストを抽出して部分ビルドを自動実行

次のステップ