自己修復: 何をするか

Latchkey ランナーが実行中に一時的な CI 障害をどのように検出し修正するか、決して触れないもの、そして修復の提案がどのようにレビュー可能なプルリクエストになるか。

すべての Latchkey ランナーには自己修復が組み込まれており、デフォルトで有効です。ワークフローのステップが失敗すると、ランナーはその障害をローカルで診断し、既知の一時的なクラスであれば修正してそのステップをその場で再試行します。人間による再実行なしにビルドがグリーンになり、すべての介入があなたが検査できるよう記録されます。

3 段階の診断カスケード#

診断は最速優先で実行されるため、よくあるケースはほとんどコストがかかりません:

何をカテゴリ別に捕捉するか#

npm ERR! code ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/react failed
npm ERR! network This is a problem related to network connectivity.

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Error: ENOSPC: no space left on device, write

/usr/bin/bash: line 1: ffmpeg: command not found

npm ERR! `npm ci` can only install packages when your package.json and
package-lock.json are in sync.

修正ツールボックス#

すべての修正はエフェメラルなランナー内でのみ適用され、ランナーはジョブの後に破棄されます:

1 つの修復、エンドツーエンドで#

これは、npm レジストリのタイムアウトという 1 つの実際の修復を、失敗したステップからグリーンなジョブまで追ったものです。あなたのステップ出力は変更されずリアルタイムでストリーミングされます。修復中は、ランナー上の修復サービスに問い合わせている間、ランナーが自身の診断行を 2 行だけ追加します:

$ npm ci
npm ERR! code ETIMEDOUT
npm ERR! syscall connect
npm ERR! network request to https://registry.npmjs.org/lodash failed, reason: connect ETIMEDOUT 104.16.92.83:443
npm ERR! network This is a problem related to network connectivity.
[latchkey-bash-wrapper] BEGIN sidecar POST (boot_wait=30s max_time=260s url=http://localhost/diagnose socket=/run/latchkey-self-heal/sock)
[latchkey-bash-wrapper] END sidecar POST ok (attempts=1 http=200)
$ npm ci
added 1291 packages, and audited 1292 packages in 42s
found 0 vulnerabilities

1. ステップが失敗します。 npm が自身の内部再試行を使い果たした後、npm ci は非ゼロで終了します。ランナーはストリーミングされるステップ出力をキャプチャしていたため、診断は全体像を手にした状態で始まります。
2. 第 1 段階、終了コード。 終了コード 1 はそれ単体では決定的ではないため、カスケードは次へ進みます。
3. 第 2 段階、パターン一致。 ETIMEDOUT の行が、パターンライブラリ内の既知の npm ネットワークシグネチャに一致します: 判定は heal、カテゴリは network、AI は関与しません。2 行の [latchkey-bash-wrapper] 行が、あなたのログにおけるこの問い合わせの唯一の痕跡です。
4. バックオフ付き再試行。 この修復の計画では、2 秒から始まる段階的な遅延を伴う最大 3 回の試行が許可されています。ランナーは待機してから、同じマシン、同じワークスペースでステップを再実行します: ログ内の 2 回目の npm ci がその再試行です。
5. グリーン。 再試行が成功し、ジョブはタイムアウトなど起きなかったかのように続行します。成功時にあなたのログへそれ以上追加されるものはありません。マシンを変更する修復はそれを告知する (たとえば [latchkey-bash-wrapper] installed package: ffmpeg) ため、見えない介入はありません。

ログでは見えなかった経緯はダッシュボードにあります: Runners ページ の Recent Heals フィードには、Pattern match のピルと取られたアクション ("Retried the npm command with exponential backoff after a network timeout") を伴う network カテゴリの Healed 行が表示され、Heal Details ドロワーが段階ごとの経緯を伝え、その実行は パイプラインパフォーマンス でグリーンの Healed バッジを保ちます。

修復プルリクエスト#

一部の根本原因は、実行中の救済だけでなく、あなたのリポジトリでの恒久的な修正に値します: ワークフローに欠けているセットアップステップ、package.json に欠けている engines の固定、低すぎるジョブのタイムアウト。成功した修復がこうした構造的な原因にさかのぼると、自己修復は構造化された提案を生成し、型付きで決定論的な編集を伴う 修復 PR を開きます。

• 各 PR のタイトルは "Latchkey heal: <error summary>" です。本文は Error、Root cause、Fix を説明し、ワークフロー実行にリンクバックするため、レビューは数分で済みます。
• 提案 PR には検証ノートが付きます: PR 自身のワークフロー実行が成功した場合は Verified by run、そうでない場合は Proposed fix, not verified by a passing run です。
• 再試行が失敗した実行を救済した場合、提案はそれを定量化します ("Latchkey auto-retried this workflow N times; M passed on the retry")。ワークフローの再試行の合格率が低い場合、自動再試行は一時停止します。
• 修復 PR が自動マージされることは決してなく、フォークからのプルリクエストには決して触れません。
• PR の作成は GitHub App の権限を使用します。修復 PR を一度もマージしなければ、あなたのリポジトリでは何も変わりません。

Declined fixes: 提案を停止する#

すべての提案クラスがすべてのリポジトリで歓迎されるわけではありません。AI Insight ページの自己修復提案の検出結果には Stop proposing アクションがあります (オーナーと管理者)。Latchkey はその後、Settings、Self-Healing、Declined fixes で取り消すまで、そのリポジトリのその障害クラスに対する PR の作成を恒久的に停止します。自己修復はそれらの障害に対して引き続き動作します。ワークフロー変更の提案だけを停止します。

することと決してしないこと#

あなたのコーディングエージェントに引き継ぐ#

自己修復は環境を修正するのであって、決してあなたのソースを修正しません。本当の問題があなた自身のコードのバグである場合、ビルドは正直に失敗し、その障害は Latchkey MCP サーバー経由で提供される完全で構造化されたバンドルとして届き、あなた自身のコーディングエージェントがそこから修正できる状態になります。このバンドルは、エージェントが本来なら手作業で再構築するものを渡します:

• 平易な言葉での 根本原因。
• 失敗したステップの 終了コード と、エラーが表面化した 正確なソースファイル。
• 失敗したステップの 完全で切り詰められていないログ。GitHub がログビューアで隠す出力を含み、Latchkey を離れる前にシークレットが除去されています。
• 自己修復が 既に調査した 内容となぜ手を引いたか、加えてワークフローの定義。

Claude Code では、組み込みの /mcp__latchkey__fix コマンドが往復を 1 ステップで行います: 直近の未修正の障害を取得し、作業に取りかかります。MCP 対応のあらゆるエージェント (Cursor、Codex など) は、サーバーのツールを通じて同じバンドルを読めます。セットアップ、API キー、そして用意済みの接続コマンドは AI エージェントを接続する にあります。

オブザーバビリティ: すべての修復が記録される#

• Recent Heals (Runners ページ 上) は、すべての介入をそのカテゴリ、判定、そして取られたアクションの平易な言葉での説明とともに一覧します。AI が診断した修復にはエージェントの推論イテレーションが含まれます。
• 修復された実行はフラグが立てられ、パイプラインパフォーマンスの実行テーブルでその修復レポートへディープリンクします。
• Runners ページの 修復の KPI と傾向 は、修復が実行を救う頻度とどのカテゴリが優勢かを示し、それ自体があなたのインフラに関するシグナルです。

コントロール#

• Settings、Self-Healing の ワークスペースレベルのスイッチ (オーナーと管理者)。新しいワークスペースではデフォルトでオンです。変更は約 1 分以内に反映されます。
• リポジトリごとのトグルはありません。ワークスペースのスイッチがすべての監視対象リポジトリに適用されます。
• Declined fixes も Settings、Self-Healing の下にあり、停止した提案クラスを一覧し、それぞれを取り消すオプションを備えています。

よくある質問#

修復が実世界のどんな障害をカバーするかを見るには、Learn の 自己修復パターンライブラリ を閲覧してください - 各エントリは手動の修正と、ランナーが自動で行うことを並べて示します。現在あなたのビルドを失敗させているものについては、完全な CI/CD エラーライブラリ から始めてください。