ドキュメントメニュー
はじめに
ダッシュボードと分析
マネージドランナー
キャッシュ
チームと通知
請求とプラン
ヘルプ
自己修復: 何をするか
Latchkey ランナーが実行中に一時的な CI 障害をどのように検出し修正するか、決して触れないもの、そして修復の提案がどのようにレビュー可能なプルリクエストになるか。
すべての Latchkey ランナーには自己修復が組み込まれており、デフォルトで有効です。ワークフローのステップが失敗すると、ランナーはその障害をローカルで診断し、既知の一時的なクラスであれば修正してそのステップをその場で再試行します。人間による再実行なしにビルドがグリーンになり、すべての介入があなたが検査できるよう記録されます。
3 段階の診断カスケード#
診断は最速優先で実行されるため、よくあるケースはほとんどコストがかかりません:
終了コードの照合 (即時)
いくつかの障害は自ら正体を明かします。終了コード 137 は、メモリを使い果たしたプロセスをカーネルが kill したものです。127 はコマンドが見つからなかったことを意味します。既知の終了コードのテーブルが、これらをその修正へ即座にマッピングします。
パターンライブラリ (決定論的)
ステップの出力は、既知の障害シグネチャの厳選されたライブラリと照合されます: npm、yarn、pnpm、pip、uv、Go モジュール、cargo、NuGet、Docker と GitHub のレジストリ、Composer、Bundler、Maven、apt、git にわたるレジストリのタイムアウトと 5xx 応答。DNS と TLS の不調。レート制限。ヒープの枯渇。ディスク満杯のエラー。ロックファイルのドリフト。パターンの一致は決定論的です: 同じ障害には毎回同じ修正です。
制限付き AI 診断 (新規の障害)
最初の 2 段階が認識しないものは、厳格な時間予算 (約 3 分) を持つサンドボックス化された AI エージェントに渡されます。キャプチャされた出力を読み、根本原因を推論し、ランナー内で安全な修正を適用するか、恒久的な修正をプルリクエストとして提案するか、あるいは障害が本物だと結論づけてそのままにします。
何をカテゴリ別に捕捉するか#
不安定な CI の最大の原因: パッケージレジストリや外部サービスの一時的な不調。あらゆる主要エコシステムにわたるタイムアウト、5xx 応答、DNS 解決の失敗、TLS ハンドシェイクエラー、レート制限。
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.
# self-heal: network/registry timeout -> retry with backoff -> passed on retry 2アウトオブメモリの kill (exit 137) と言語ランタイムのヒープ枯渇。修正は NODE_OPTIONS=--max-old-space-size=4096 や _JAVA_OPTIONS=-Xmx4g などの環境変数で再試行時の上限を引き上げます。
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
# self-heal: memory/node heap -> set NODE_OPTIONS=--max-old-space-size=4096 -> retriedENOSPC およびディスク満杯の障害。修正は Docker レイヤーと npm、pip、yarn、Gradle、cargo のキャッシュ、加えて /tmp を削除して空き容量を確保し、ステップを再試行します。
Error: ENOSPC: no space left on device, write
# self-heal: disk/full -> pruned docker + package caches (14.2 GB freed) -> retriedジョブが決してインストールしなかったツールをステップが前提とします (exit 127、"command not found")。修正は、検証済みの許可リスト (GitHub ホステッドランナーイメージにある同じパッケージセット) から欠けているシステムパッケージをインストールして再試行します。許可リスト外のツールは意図的にそのままにされます。
/usr/bin/bash: line 1: ffmpeg: command not found
# self-heal: tool_missing -> apt-get install ffmpeg (allowlisted) -> retried既知の安全な書き換えを伴う既知の構成の不一致。たとえば、npm ci が失敗するが npm install が文書化された対処法である、マニフェストと同期していないロックファイルなど。
npm ERR! `npm ci` can only install packages when your package.json and
package-lock.json are in sync.
# self-heal: config/lockfile drift -> command rewrite: npm ci -> npm install -> retried修正ツールボックス#
すべての修正はエフェメラルなランナー内でのみ適用され、ランナーはジョブの後に破棄されます:
修復がログでどう見えるか#
あなたのステップ出力は、変更されずリアルタイムでストリーミングされます。修復が起きると、ランナーの診断行がその横に現れるため、介入が見えなくなることは決してありません:
$ npm ci
npm ERR! code ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/lodash failed
# [latchkey-bash-wrapper] step failed (exit 1), diagnosing...
# [latchkey-bash-wrapper] verdict: network/registry-timeout (stage 2 pattern match)
# [latchkey-bash-wrapper] action: retry with backoff (attempt 1 of 3, waiting 5s)
$ npm ci
added 1291 packages in 42s
# [latchkey-bash-wrapper] heal successful, continuing job修復プルリクエスト#
一部の根本原因は、実行中の救済だけでなく、あなたのリポジトリでの恒久的な修正に値します: ワークフローに欠けているセットアップステップ、package.json に欠けている engines の固定、低すぎるジョブのタイムアウト。成功した修復がこうした構造的な原因にさかのぼると、自己修復は構造化された提案を生成し、型付きで決定論的な編集を伴う 修復 PR を開きます。
- 各 PR のタイトルは "Latchkey heal: <error summary>" です。本文は Error、Root cause、Fix を説明し、ワークフロー実行にリンクバックするため、レビューは数分で済みます。
- 修復 PR が自動マージされることは決してなく、フォークからのプルリクエストには決して触れません。
- PR の作成は GitHub App の権限を使用します。修復 PR を一度もマージしなければ、あなたのリポジトリでは何も変わりません。
することと決してしないこと#
自己修復がすること
- 同じランナー上で、失敗したステップをバックオフ付きで再試行する
- 実行のためにメモリ上限を引き上げ、ディスク容量を解放する
- 許可リストにある欠けたシステムパッケージをインストールする
- 恒久的な修正をレビュー可能なプルリクエストとして提案する
自己修復が決してしないこと
- 実行中にあなたのコードやリポジトリを変更する
- 何かをマージする: リポジトリの変更はあなたがレビューする PR としてのみ届く
- 本物の障害を隠す: 修復不能なステップは元のログを保ったまま失敗する
- フォークからのプルリクエストに触れる
あなたのコーディングエージェントに引き継ぐ#
自己修復は環境を修正するのであって、決してあなたのソースを修正しません。本当の問題があなた自身のコードのバグである場合、ビルドは正直に失敗し、その障害は Latchkey MCP サーバー経由で提供される完全で構造化されたバンドルとして届き、あなた自身のコーディングエージェントがそこから修正できる状態になります。このバンドルは、エージェントが本来なら手作業で再構築するものを渡します:
- 平易な言葉での 根本原因。
- 失敗したステップの 終了コード と、エラーが表面化した 正確なソースファイル。
- 失敗したステップの 完全で切り詰められていないログ。GitHub がログビューアで隠す出力を含み、Latchkey を離れる前にシークレットが除去されています。
- 自己修復が 既に調査した 内容となぜ手を引いたか、加えてワークフローの定義。
Claude Code では、組み込みの /mcp__latchkey__fix コマンドが往復を 1 ステップで行います: 直近の未修正の障害を取得し、作業に取りかかります。MCP 対応のあらゆるエージェント (Cursor、Codex など) は、サーバーのツールを通じて同じバンドルを読めます。セットアップ、API キー、そして用意済みの接続コマンドは AI エージェントを接続する にあります。
オブザーバビリティ: すべての修復が記録される#
- Recent Heals (Runners ページ 上) は、すべての介入をそのカテゴリ、判定、そして取られたアクションの平易な言葉での説明とともに一覧します。AI が診断した修復にはエージェントの推論イテレーションが含まれます。
- 修復された実行はフラグが立てられ、パイプラインパフォーマンスの実行テーブルでその修復レポートへディープリンクします。
- Runners ページの 修復の KPI と傾向 は、修復が実行を救う頻度とどのカテゴリが優勢かを示し、それ自体があなたのインフラに関するシグナルです。
| シグナル | 何を伝えるか |
|---|---|
| 結果バッジ | Healed (修正が成功)、No Action (システムが意図的に行動しなかった。たとえばあなた自身のコードの障害で)、Failed (修正が試みられたがステップを回復できなかった)、または Pending (結果がまだ記録されていない)。 |
| 修正タイプのピル | 修復がどう決定されたか: Auto-fix (決定論的な終了コードルール)、Pattern match (既知の修正を伴う既知の障害シグネチャ)、または Agent fix (エージェントが調査した)。 |
| エージェントのトランスクリプト | エージェント修復のステップごとの記録: 計画、ターンごとの仮説と推論、各アクションとその結果、そして所要時間。 |
コントロール#
- Settings、Self-Healing の ワークスペースレベルのモード (オーナーと管理者)。変更は約 1 分以内に反映されます。
- Runners ページ の 構成ごとのトグル。特定のランナータイプを除外できます。
- 現在リポジトリごとのトグルはありません。ワークスペースのモードがすべての監視対象リポジトリに適用されます。
よくある質問#
自己修復はビルドを遅くしますか?
いいえ。ステップが失敗したときにのみ作動します。成功するステップは追加のレイテンシーゼロで実行されます。修復された障害には診断と再試行のコストがかかりますが、これは人間が赤いビルドに気づいて再実行をクリックするよりほぼ常にはるかに安上がりです。
私のシークレットを見られますか?
診断は、ジョブが既に出力するステップ出力に対して、あなたのランナー上でローカルに実行されます。新たに露出されるものはありません: GitHub Actions によってマスクされたシークレットはマスクされたままで、ランナーはジョブの後に破棄されます。
永遠に再試行して請求額を膨らませることはありますか?
いいえ。再試行はステップごとに制限され、AI 段階には厳格な時間予算があり、ランナー自体に 4 時間の寿命上限があります。また自己修復に別途料金はありません: 修復中の追加ランタイムはランナーの標準的な 1 分あたりの料金で課金されます。
障害を修正できない場合はどうなりますか?
そのステップは他のどのランナーとも同じように、元のログを保ったまま失敗し、加えて Recent Heals で読める診断が付きます。修復不能は、エラーではなく一級の判定です。
修復が実世界のどんな障害をカバーするかを見るには、Learn の 自己修復パターンライブラリ を閲覧してください - 各エントリは手動の修正と、ランナーが自動で行うことを並べて示します。現在あなたのビルドを失敗させているものについては、完全な CI/CD エラーライブラリ から始めてください。