# AI Scan によるカスタムランナー

> 独自のラベルを持つ適切なサイズのランナー構成を作成します: AI にワークフローをスキャンさせて形状を提案させ、そのラベルをプリセットのように使います。

Source: https://latchkey.dev/ja/documentation/custom-runners

## Summary

- **AI Scan** はワークフローを分析し、独自の `latchkey-<name>` ラベルを持つ適切なサイズの構成を提案します。
- イメージビルドは通常 10-15 分かかります。一般的な結果はビルドが 30-50% 高速化することです。ジョブ開始時に何もインストールする必要がないためです。
- 新しいラベルを狙ったジョブは、そのイメージビルドが完了するまでキューに入ります。準備完了時に通知されます。
- 上限: Developer と Launch で 2、Scale で 10、Enterprise で無制限。カスタムランナーは xlarge の料金 ($0.0200/min) で課金されます。

4 つのプリセットが合わない場合 (メモリを大量に消費する統合スイート、CPU バウンドのコンパイル) は、独自の `latchkey-<name>` ラベルとあなたが選ぶ形状を持つ **カスタムランナー構成** を作成します。最速の方法は [Runners ページ](/documentation/runners-dashboard) の **AI Scan** です。

## プリセットかカスタムか?

決め手はコストの微調整ではなく形状です。カスタムランナーは、選ぶ形状にかかわらず xlarge の料金 ($0.0200/min) で課金されるため、合うものがあればプリセットがほぼ常により安い選択肢です。公開価格を用いた具体例: 32 GB のメモリを必要とするテストスイートは `latchkey-large` (8 vCPU / 32 GB) に $0.0100/min で収まりますが、同じ 32 GB のメモリ最適化のカスタム形状は $0.0200/min で課金されます。カスタムにするのは、そのジョブにどのプリセット比率も合わないからであって、vCPU を 1 つ削るためではありません。

カスタム構成は、ほとんどのプランで限られたリソースでもあります (Developer と Launch で 2、Scale で 10、Enterprise で無制限)。したがって、同じ形状のわずかなバリエーションではなく、本当に異なるワークロードに使ってください。プランごとの数は [上限と同時実行数](/documentation/runner-limits) にあります。

## AI Scan の仕組み

[Runners ページ](/documentation/runners-dashboard) で **AI Scan Runners** をクリックし、監視対象リポジトリの 1 つを選びます。リストは検索可能で、各リポジトリの名前、主要言語、プライベートかどうかを表示します。**Scan Repository** をクリックすると、進捗が 3 つのステップ (リポジトリのスキャン、技術スタックの分析、構成の生成) にわたって経過タイマー付きでライブ表示されます。

見守る必要はありません。**Run in background** はモーダルを閉じ、スキャンはサーバー側で実行され続けます。Runners ページの進捗ピルが、各アクティブなスキャンを **Queued**、**Scanning repository**、**Optimizing workflows**、**Ready for review** の各段階で追跡し、表示、レビューとカスタマイズ、または 1 クリックでの承認のアクションを提供します。

## 結果を読む

結果は、リポジトリ名と **全体の信頼度パーセンテージ** とともに開きます。これは検出と構成に関する AI 自己評価の確信度です。スキャンは証拠に基づきます: CPU やメモリの数字を推測させる代わりに、あなたが実際に実行するワークフロー、依存関係のマニフェスト、ビルドステップを読み取り、あなたがレビューして承認するまで何も作成されません。このスコアはまさにそのとおり、承認前にどれだけ細かく確認すべきかの目安として扱ってください。

- **Detected Tech Stack** セクションは、言語、フレームワーク、ビルドツール、パッケージマネージャーの下に検出結果をまとめます。各項目は名前、検出された場合はそのバージョン、信頼度バッジを表示します: 信頼度 80% 以上で High、50% 以上で Medium、50% 未満で Low、それぞれ正確なパーセンテージ付きです。
- スキャンが検出した場合は **モノレポインジケーター** が表示されます。ランナーは最も要求の厳しいサブパッケージに合わせてサイズが決められます。
- その下には **提案された構成** があります: 生成されたランナー名、推奨サイズ、プリインストールするランタイムとバージョン、構成するキャッシュ、環境変数、事前プルする Docker イメージ、そして選択理由を説明する平易な言葉のノート要約。

### パッケージの解決

何かを承認する前に、検出されたパッケージは 3 つのバケットに分類されるため、イメージに何が含まれるかについて驚きがありません:

| バケット | 意味 |
| --- | --- |
| 既にベースランナーイメージにある | そのツールはすべての Latchkey ランナーイメージにバージョン固定で同梱されています。追加でインストールするものはありません。 |
| あなたのランナーに追加される | そのツールはあなたのカスタムイメージに焼き込まれ、分単位の推定ビルド時間が表示されます。 |
| ワークフロー YAML に保持される | Latchkey はこのツールを事前に焼き込めないため、CI 実行時のインストールステップとして残ります。 |

## 承認してビルドする

**Approve & Build** はランナーを作成し、そのイメージのビルドを開始します。代わりに **Skip scan results** は推奨を破棄します。ランナーはすぐに **Your runners** テーブルに現れ、ステータスバッジが **Pending Build** から **Building**、**Ready** へと移り、ビルドは通常 10-15 分かかります。ビルドが失敗した場合、バッジは **Failed** を表示し、ランナーの詳細ビューから再試行できます。ビルドが完了した瞬間に "AI scan runner is ready" の通知を受け取り、それ以降ラベルはあらゆるプリセットのように振る舞います。

> **イメージのビルド中**
> イメージの準備が整う前に新しいラベルを狙ったジョブはキューで待機します。ビルドが失敗すると通知され、Runners ページの構成の行にビルド状況が表示されます。

## 最適化 PR

Latchkey はワークフローの変更をあなたに代わって行うこともできます。あなたのリポジトリにプルリクエストを開き、ワークフローを新しいランナーのラベルに切り替え **さらにイメージが不要にするセットアップステップを削除** します。ランナー起動時にそれらのツールは既にインストールされているためです。Runners ページのバナーが、最適化されたワークフローを **View Pull Request** ボタンとともに知らせます。マージ後の一般的な結果: ビルドが 30-50% 高速化します。ジョブ開始時に何もインストールする必要がないためです。この PR は Linux ジョブを切り替えます。Windows と macOS のジョブは手を付けられません。

## ルール

| 項目 | ルール |
| --- | --- |
| ラベル | `latchkey-<name>`: 小文字、数字、ハイフン。プリセット名と衝突してはいけません |
| 形状 | general、compute、memory-optimized の各ファミリーにまたがる CPU/メモリプロファイル |
| ディスク | 100 から 500 GB |
| いくつまで | Developer と Launch: 2 つのカスタム構成、Scale: 10、Enterprise: 無制限 |
| 課金 | カスタムランナーは xlarge の料金 ($0.0200/min) で課金されます |

命名の提案を 1 つ: `latchkey-integration-xl` のように、形状ではなくワークロードにちなんでラベルを名付けてください。ワークロード名は、ジョブのニーズが変わってもワークフローファイル内で真実であり続け、次に読む人にそのランナーが何のためのものかを伝えます。

## 使い方

```.github/workflows/integration.yml
jobs:
  integration:
    runs-on: latchkey-integration-xl   # your custom label
    steps:
      - uses: actions/checkout@v4
      - run: make integration-test
```

それ以外はすべてプリセットのように振る舞います: エフェメラルなシングルジョブのマシン、自己修復込み、プランに対して計測される分数。

## イメージを同期させ続ける

詳細ドロワーの **AI Scan Source** カードは、ソースリポジトリ、最後にスキャンされた日時、そして **Rescan Repository** ボタンを表示します。再スキャンの結果は差分として返ってきます: 追加されたパッケージ、削除されたパッケージ、推奨サイズの変更。**Apply Changes** は構成を更新してイメージを再ビルドします。**Dismiss** はすべてをそのままにします。何も変わっていなければ、ドロワーはランナーが既に最新であることを伝えます。

## ビルド履歴と設定

詳細ドロワーは **直近 10 件のイメージビルド** をステータス (保留中、ビルド中、成功、または失敗)、開始時刻、ビルド所要時間、そして失敗があればそのエラーメッセージとともに一覧します。これにより、ビルドが失敗したとき、サポートチケットを提出せずに理由を確認できます。

各ランナーはリネーム、追加ラベルの付与、**Max Concurrent** 上限の設定 (0 は無制限を意味します)、アクティブのオン/オフの切り替え、または確認付きの削除ができます。管理アクションは管理権限を持つ組織ロールが利用でき、それ以外の全員は同じ詳細を読み取り専用で見ます。

### AI Scan は何をしますか?

ワークフローを分析し、独自の `latchkey-<name>` ラベルを持つ適切なサイズのランナー構成を提案して、ジョブが実際に使うものを事前インストールします。ジョブ開始時にインストールが発生しないため、一般に 30 〜 50% 高速なビルドになります。

### カスタムランナーのイメージビルドにはどれくらいかかりますか?

通常 10 〜 15 分です。新しいラベルを指定したジョブは失敗せずにビルド完了までキューで待機し、イメージの準備ができると通知されます。そのため、ビルド完了前にワークフローの変更をマージしても問題ありません。

### カスタムランナーはいくつ作れて、費用はいくらですか?

Developer と Launch で 2 つ、Scale で 10 個、Enterprise は無制限です。カスタムランナーは設定したサイズに関わらず xlarge の料金である 1 分 $0.0200 で課金されるため、節約は単価ではなくジョブ時間の短縮から生まれます。

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt