AIチュートリアル

RepoPilotで検証主導のGitHub Issue・PR修正を実行する方法

RepoPilotのインストール、信頼できるテストとリポジトリポリシーの設定、プルリクエストのレビュー、Issueの再現、Codexが生成した修正の検証、タスク管理について説明します。さらに、メンテナーが管理権限を維持したまま、条件を満たす修正をドラフトプルリクエストとして公開する方法も紹介します。

2026年9月18日約19分で読了

RepoPilotの機能

RepoPilotは、検証駆動のソフトウェア反復開発に対応するセルフホスト型コントローラーです。選択したGitHub Issueと同一リポジトリ内のプルリクエストを、ルールレビュー、テスト生成、失敗の再現、コード修正、独立検証、さらに修正ブランチとドラフトプルリクエストの任意公開までを含む、範囲を限定したワークフローに変換します。

このプロジェクトでは、OpenAI Codex SDKを使用して、リポジトリのルールを理解し、要件駆動のテストを設計し、本番コードの変更を提案します。別のDockerランナーが、固定されたリポジトリスナップショットに対してテストを実行します。コントローラーは、設定された証拠とポリシーチェックに合格した場合にのみ結果を公開します。

RepoPilotは変更を自動的にマージまたはデプロイしません。メンテナーが作業を選択して証拠をレビューし、最終的なマージ判断を行います。

ワークフローの制約

RepoPilotは、関連するベースコミットとヘッドコミットを固定します。
適用可能なAGENTS.mdのガイダンスを含め、ベースブランチから信頼済みのポリシーを読み込みます。
Codexが変更をレビューし、テストまたは修正候補を提案します。
本番コードを修正する前に、生成されたテストを凍結します。
別のランナーが独立したスナップショットに対してテストを実行します。
コントローラーが、安定したテスト識別子、失敗フィンガープリント、保護対象パス、ポリシー結果、設定された上限を確認します。
条件を満たす結果は、別のブランチに配置し、人によるレビュー用のドラフトプルリクエストとして提出できます。

プルリクエストの場合、RepoPilotはベースとヘッドの動作を比較します。Issueの場合は、まず元のベースラインが合格することを確認し、新たに凍結したテストで報告された不具合の再現を試みてから、修正を提案します。

主な機能と現在の範囲

入力の固定: ベースとヘッドのSHA、タイトルと本文のダイジェスト、鮮度チェック、キャンセルにより、古い入力に対する検証を防ぎます。
信頼済みリポジトリルール: 静的ポリシーは、リテラルチェックとJavaScriptまたはTypeScriptの呼び出しルールに対応します。ベースブランチ内のネストされたAGENTS.mdファイルで、意味的なレビューを指示できます。
独立したテスト実行: コントローラーはモデルの評価を信頼せず、別のDockerランナーに実行を委任します。
複数のテストエコシステム: Version 1.3.0では、Nodeのテストランナー、Vitest、pytest、Goテスト、互換性のあるJUnit XML証拠に対応しています。
モノレポ対応: 作業ディレクトリ、名前付きの複数テストコマンド、一時的な依存サービスを設定できます。
範囲を限定した修正: 試行回数、再試行回数、モデル呼び出し、トークン、タスク実行回数、タスク全体の時間に上限を設定できます。
追跡可能なレポート: アトミックなJSONレポートと短縮版Markdownサマリーに、検出事項、テスト結果、パッチ、試行、公開状態を保持します。
運用上の復旧: タスクコマンドで、検査、キャンセル、再開、再実行に対応します。recoverフローでは、プレビューと検証済みクリーンアップを通じて、所有対象のクラッシュ残留物を処理します。

現在の実装は、最大10,000ファイルまたは16 MiBまでの公開テキストベースリポジトリを対象としています。フォークからのプルリクエスト実行、ブラウザーのエンドツーエンドテスト、ホスト型ダッシュボード、Webhook、分散キュー、自動依存関係インストール、自動マージ、デプロイには対応していません。

前提条件

Node.jsをインストールしたくない場合は、Linux、Windows、macOS向けのRepoPilot 1.3.0ポータブルリリースをダウンロードできます。ソースからインストールする場合は、以下を準備してください。

推奨バージョンであるNode.js 22
npmとGit
Linuxコンテナを実行するよう設定されたDocker
Codexを利用したレビュー、テスト計画、または修正を有効にする場合のOpenAI APIキー
GitHubへのアクセスまたは公開が必要な場合のGitHubトークン

ControllerとAgentのイメージバージョンは1.3.0で一致させてください。テストコンテナはデフォルトでネットワークにアクセスできないため、Dockerイメージとプロジェクトの依存関係は事前に用意する必要があります。

ソースからRepoPilotをインストールする

1. プロジェクトをインストール、検証、ビルドする

クローンしたRepoPilotリポジトリで、固定された依存関係をインストールし、プロジェクトのチェックとテストを実行して、コントローラーをビルドします。

npm ci
npm run check
npm test
npm run build

RepoPilot独自の開発用テストでは、モック化されたAPI、エージェント、ランナー、合成フィクスチャを使用します。モデルクレジットを消費したり、Dockerを起動したり、GitHubのコンテンツを書き込んだりすることはありません。

2. ローカル設定を作成する

用意されているサンプル設定をコピーします。

cp repopilot.example.json config.local.json

PowerShellユーザーは、cpの代わりにCopy-Itemを使用できます。config.local.jsonを編集して、対象リポジトリと信頼済みのテストコマンドを指定します。このローカル設定は、レビュー対象のリポジトリスナップショットの外部に置いてください。

サンプル設定では、エージェントによるレビュー、修正、公開が無効になっています。ローカル検証が機能することを確認してから、これらの機能を個別に有効にしてください。

3. Codex Agentイメージをビルドする

Codexを利用した意味的なレビュー、テスト計画、または修正を行う場合は、Agentコンテナをビルドします。

docker build -f Dockerfile.agent -t repopilot-agent:local .

コントローラーの環境にOPENAI_API_KEYを設定します。このキーを受け取るのはAgentコンテナだけです。デスクトップ版ChatGPTの認証情報は再利用されません。GITHUB_TOKENまたはGH_TOKENを通じて提供されたGitHub認証情報は、コントローラー内に残ります。

最初のローカルプルリクエストチェックを実行する

ベースブランチと機能ブランチをローカルで比較することから始めます。

npm run dev -- check --config config.local.json --repo /path/to/project --base main --head feature

/path/to/project、main、featureを、ローカルリポジトリと使用する参照に置き換えてください。ローカルでのcheckは変更を公開せず、ソースチェックアウトも編集しません。

RepoPilotによる生成テストの分類方法

生成されたシナリオは、regressionまたはnew_behaviorのいずれかに分類されます。デフォルトは回帰です。

回帰の証拠: 同じテストケースを実行した結果、ベースリビジョンでは成功し、ヘッドリビジョンでは失敗する。
新しい動作の証拠: ベースでは失敗し、ヘッドでは成功する。また、提案されたテストにプルリクエストのタイトルまたは本文からの要件の正確な引用が含まれている。
レビューが必要: 両方のリビジョンで失敗する、ケースがスキップまたは欠落している、実行に失敗する、テスト検出が変更される、または元のテスト結果が予期せず変わる。

モデルが提供するラベルで、ランナーの証拠を上書きすることはできません。回帰が自動修復の対象になるには、同一の失敗テスト識別子とフィンガープリントで失敗が繰り返し確認される必要があります。

プルリクエストを継続的にレビューする

RepoPilotのウォッチャーは、非ドラフトで同一リポジトリにあるプルリクエストをポーリングし、自身のautofixブランチを除外します。設定を検証する間、ポーリングを1サイクル実行します。

npm run dev -- watch --config config.local.json --once

結果を確認したら、ウォッチャーを継続的に実行します。

npm run dev -- watch --config config.local.json

公開はオプトインであり、publish=trueが必要です。GitHubトークンには、リポジトリのContentsおよびPull requestsへの書き込み権限が必要です。公開によって個別のautofixブランチとドラフトプルリクエストが作成されます。自動的に強制プッシュやマージが行われることはありません。

公開前に、RepoPilotはコミットSHAとプルリクエストの説明を再確認します。既存の修復ブランチまたはプルリクエストは、その親とツリーが検証済みの結果と一致する場合にのみ再利用できます。

GitHub Issueを再現して修復する

Issueの修復は、メンテナーが明示的に選択します。Issue 123を処理するには、次を実行します。

npm run dev -- fix --issue 123 --config config.local.json

Issueワークフローは、主に次の3段階で進みます。

ベースラインを確立する: 固定された対象リビジョンで、既存のテストが成功する必要があります。
バグを再現する: RepoPilotはIssueの説明に関連付けたテストを生成して固定します。新しいテストで報告された失敗を再現できなければなりません。
修復を試みて検証する: Codexがコードの置換案を提示し、独立したランナーが固定された生成テスト、元のテストスイート、リポジトリポリシーを確認します。

証拠が不十分、不安定、または不完全な場合、ワークフローは人間によるレビューのために停止します。RepoPilotがIssueを自律的に選択したり、製品ロードマップを定義したり、結果として得られた修復をマージしたりすることはありません。

信頼できるリポジトリポリシーを追加する

対象のベースブランチに.repopilot/policy.jsonをコミットします。たとえば、次のルールは無効化されたJavaScriptおよびTypeScriptテストを拒否します。

{
  "rules": [
    {
      "id": "no-disabled-tests",
      "kind": "forbid-call",
      "extensions": [".ts", ".js"],
      "callee": "test.skip",
      "message": "回帰テストを有効にしてください。",
      "severity": "error"
    }
  ],
  "exceptions": []
}

サポートされている静的ルール種別には、forbiddenText、forbid-call、require-callがあります。呼び出しルールは、直接呼び出し、修飾された呼び出し、文字列によるプロパティアクセスを検査します。エイリアスの解決やプログラム全体の解析は行いません。リテラルルールはコメントにも一致する場合があります。

ポリシーの例外では、ruleId、完全一致のパス、理由、UTCの有効期限タイムスタンプ、任意の完全一致の証拠を指定できます。例外がベースポリシーに由来する場合にのみ信頼され、期限切れの例外で検出結果を抑制することはできません。

必須ルールと禁止ルールが重複すると、レビューは停止します。信頼されたルールファイルを変更するプルリクエストにはメンテナーのレビューが必要であり、そのプルリクエスト自身の修復を承認することはできません。

テストの証拠を慎重に設定する

デフォルトのレポーターはnodeで、node --testを使用します。信頼されたレポーターを利用できるよう、まずRepoPilotをビルドしてください。Vitestの場合はreporter=vitestを設定し、依存関係を固定した信頼済みイメージで明示的なvitest runコマンドを使用します。

レポーターのフラグは、信頼されていないテストコマンドではなくコントローラーに指定します。
reporter=commandは出力のみを収集し、検証や公開には対応できません。
ランナーを省略すると、ポリシーのみのレビューになり、テストはnot_runとして記録されます。
テストが0件、すべてスキップされたテスト、形式が不正なレポート、テスト識別子の欠落は、成功として扱われません。
設定された依存サービスは、使い捨ての内部Dockerネットワークを使用します。

ベースリビジョンに存在しないエクスポートを含む生成テストでは、実行中のテストケース内でそのエクスポートの有無を確認してください。構造化された証拠を収集する前に、トップレベルのインポートで欠落したエクスポートがクラッシュを引き起こしてはなりません。

実行中および完了済みのタスクを管理する

RepoPilotは.repopilot-dataの下にレポートとスナップショットを保存します。各タスクにはJSON形式の証拠とMarkdown形式の概要が作成されます。再試行された実行では、以前の証拠がTASK.execution-N.jsonのような名前でアーカイブされます。

タスクを確認してキャンセルする

npm run dev -- tasks list --config config.local.json --status running --limit 20 --offset 0
npm run dev -- tasks show TASK_ID --config config.local.json --format markdown
npm run dev -- tasks cancel TASK_ID --config config.local.json

コントローラーが書き込みロックを保持している間も、タスクの一覧表示、詳細表示、キャンセルは利用できます。キャンセルすると永続的なリクエストが作成され、検証および公開の際に確認されます。すでに完了したGitHubへの書き込みを取り消すことはできません。

作業を再開または再実行する

npm run dev -- tasks resume TASK_ID --config config.local.json
npm run dev -- tasks rerun TASK_ID --config config.local.json

resumeはタスクの識別情報、設定、制限値を維持します。状態に応じて、検証を再開するか、検証済みタスクの公開を続行します。rerunは、元の固定コミットと現在の設定を使用して関連付けられたタスクを作成し、以前のレポートとキャンセルマーカーを保持します。

永続的な状態、終了状態、または上限を使い果たしたタスクには再実行が必要です。リプレイには記録されたローカルリポジトリまたはGitキャッシュも必要であり、プルリクエストの入力はリプレイ中に再度確認されます。

高度な運用のヒント

保守的な制限値を使用する

タスクのタイムアウト、maxCalls、maxAttempts、maxTaskExecutions、トークン使用量には、上限のある値を設定してください。maxTokensの値は、各モデル呼び出し後に報告される使用量から計算されるため、1回の呼び出しで超過する場合があります。これは厳密な金銭的支出上限として扱わないでください。

環境障害を分けて扱う

RepoPilotは障害を分類し、対象となる環境問題に対してフェーズ単位の上限付きリトライを適用します。不安定なテスト、変化する検出結果、または不完全な証拠は、確認済みのコード欠陥として扱われるのではなく、自動修復を阻止します。

証拠の連鎖を保護する

修復候補は、ワークフローの要件に従い、生成されたテストの識別情報を維持し、元のベース、元のヘッド、生成されたケースを渡す必要があります。既存のテスト、マニフェスト、設定、ポリシー、隠しパスは保護されます。候補修復後には、静的および意味的なポリシーチェックが再度実行されます。

クラッシュ後は慎重に復旧する

バージョン1.3.0には、中断されたタスクが所有するリソースをプレビューし、明示的にクリーンアップするためのrecoverワークフローが含まれています。古いプロセスが停止していることを確認してから、残存ロックを削除してください。従来のロックやリソースについては、手動での確認が必要になる場合があります。

信頼境界を理解する

コントローラー、レポート、ランナーはお使いのマシンまたはワーカー上で動作しますが、Codexのモデル呼び出しではOpenAIのサービスを使用し、選択されたリポジトリのテキストとタスクコンテキストを送信します。RepoPilotをセルフホストしても、オフラインのモデル推論は提供されません。

テストの実行が提供するのはエンジニアリング上の証拠であり、悪意のあるコードに対する改ざん防止認証ではありません。シンボリックリンク、サブモジュール、バイナリ、大小文字が衝突するパスはフェイルクローズされます。信頼できないリポジトリを実行する前に、プロジェクトのセキュリティガイダンスを確認してください。

まとめ

RepoPilotは、Codexを活用したレビューと修復を、固定された入力、凍結されたテスト、独立したDocker実行、リポジトリポリシー、上限付きリトライ、永続的な証拠と組み合わせます。まずは公開を行わないローカルのcheckから始め、レポーターとポリシーの設定を検証してください。その後、証拠がチームの基準を満たした場合に限り、監視、Issueの修復、ドラフトプルリクエストの公開を追加します。