# GitHub ホステッドランナーからの移行

> 完全な移行ガイド: 実際に何が変わるか、3 つの移行パス、Migrate Runners ツールが適用する正確なラベルマッピング、PR に含まれる内容、検証、そしてロールバック。

Source: https://latchkey.dev/ja/documentation/migrate-from-github-hosted

## Summary

- 変わるのは `runs-on:` ラベルだけです。actions、シークレット、environments、GitHub 側のキャッシュは手つかずのまま機能し続けます。
- 3 つのパス: **Migrate Runners** ツール (リポジトリごとに 1 つの PR、1 回のパスで最大 20 の監視対象リポジトリ)、1 行の手動編集、または適切なサイズのイメージのための AI Scan。
- ツールは標準の Ubuntu ラベルを `latchkey-small` にマッピングし、Windows や macOS のジョブ、認識されないラベル、`${{ }}` 式には決して触れません。
- ロールバックは 1 回のリバートです: 移行 PR を取り消せば、ジョブは即座に GitHub ホステッドへ戻ります。

Latchkey ランナーへの移行は、書き直しではなくルーティングの変更です。どのランナーがジョブを引き受けるかを決めるのは `runs-on:` ラベルだけであり、移行が触れるのもそれだけです。それ以外のすべては以前とまったく同じように機能し続けます: あなたが呼び出す actions、GitHub が注入するシークレット、environments とその保護ルール、そして GitHub 側のキャッシュ。さらに、GitHub ホステッドのラベルは `latchkey-*` ラベルと並行して機能し続けるため、完全な切り替えを強いられることはありません。

## 何が変わり、何が機能し続けるか

## 始める前に

**前提条件**
- [ ] Latchkey GitHub App が私の組織にインストールされている
- [ ] 移行したいリポジトリが Latchkey で監視されている
- [ ] 私のトライアルまたはサブスクリプションがアクティブである

## 移行する 3 つの方法

3 つのパスは組み合わせられます: ほとんどのチームは、パイロットとして 1 つのワークフローを手動で編集し、ツールで一括移行し、独自のイメージに値する少数のリポジトリには AI Scan を使います。

| パス | 適した用途 |
| --- | --- |
| **Migrate Runners** ツール | 一括移行: 1 回のパスで最大 20 の監視対象リポジトリ、それぞれにレビュー可能な PR を 1 つ |
| `runs-on:` の手動編集 | 単一のワークフロー、パイロットジョブ、またはツールが認識しないラベル |
| [AI Scan](/documentation/custom-runners) | プリセットではなく、適切なサイズのカスタムイメージに値するリポジトリ |

### パス 1: Migrate Runners ツール

このツールには 2 つの入口があり、どちらも同じモーダルを開きます: ダッシュボードのサイドバーにある **Migrate Runners** 項目と、[Runners ページ](/documentation/runners-dashboard) の Runner Types カードのフッターにある CTA です。移行 PR を開くにはオーナーまたは管理者のロールが必要です。

チームがそのプルリクエストをマージするまで、リポジトリでは何も変わりません。リポジトリに既に開いている移行 PR がある場合、ツールは重複を開く代わりにそれへリンクします。切り替えるものが何も残っていない場合は、**Nothing to migrate** の状態を表示します。移動するリポジトリが 20 を超える場合は、複数回のパスに分けて移行してください。

### ツールが適用する正確なマッピング

| あなたのワークフロー内 | PR が行うこと |
| --- | --- |
| `ubuntu-latest`、`ubuntu-24.04`、`ubuntu-22.04` | 最低コストのサイズである `latchkey-small` に切り替え |
| その他の Linux サイズ指定 | その CPU とメモリを満たす最小の Latchkey サイズに切り替え |
| Windows と macOS のジョブ | そのまま残されます |
| ツールが認識しない self-hosted ラベル | そのまま残されます |
| `${{ matrix.os }}` のような `${{ }}` 式を含むあらゆる行 | そのまま残されます |

手を付けない行は意図的なものです: ツールが確信を持ってルーティングできないジョブは、今日とまったく同じ場所で実行され続けるため、Linux フリートを今すぐ移行しつつ、OS 混在のワークフローは安全に手つかずのまま残せます。ツールがスキップしたものも、準備ができたときにいつでも手動で移動できます。

### 各プルリクエストに含まれるもの

各 PR は `runs-on:` の行を書き換え、それ以外には何もしません。PR 本文自身が述べるとおり、"Only runs-on: lines were touched. Every other line in each file is byte-identical." 唯一の例外: 移行が Latchkey のキャッシュステップも注入する場合、それらのステップが `runs-on` の行以外の唯一の追加であり、本文にもそう記されます。各ファイルの変更前後のマッピングテーブルが、何が変わったかを正確に示すため、レビューには数日ではなく数分しかかかりません。

### パス 2: 単一のワークフローを手動で編集する

1 つのワークフローであれば、変更はジョブごとに 1 行で、どちらのラベル形式も同じようにルーティングされます:

最初の実行の検証やサイズの選択を含む、このパスのステップバイステップ版は [最初のジョブを実行する](/documentation/run-your-first-job) です。

### パス 3: AI Scan、独自のイメージに値するリポジトリ向け

一部のリポジトリはラベルの置き換え以上の価値があります。**AI Scan** はリポジトリが実際に実行するワークフローを読み取り、適切なサイズの形状と、リポジトリのツールチェーンをプリインストールするイメージを備えたカスタムランナー構成を提案します。これによりジョブはセットアップステップを丸ごとスキップできます。心当たりのあるリポジトリがあれば、[AI Scan によるカスタムランナー](/documentation/custom-runners) から始め、そのリポジトリをプリセットではなくカスタムラベルに移行してください。

## 段階的な戦略

一括移行は必要なく、避けることをお勧めします。低リスクのリポジトリ 1 つ、理想的には、安い分、速いピックアップ、自己修復が最も見えやすい不安定または遅いリポジトリから始め、フリート全体を移す前に 1 週間実行させてください。

GPU、Windows、macOS、arm64 ホストを必要とするジョブは GitHub ホステッドや他のランナーに留まり、それはいつまでもそのままで問題ありません: `runs-on` はジョブごとに決定されるため、ワークフローは Latchkey と GitHub ホステッドのジョブを自由に混在させられます。

## マージ後に検証する

1. **ジョブがどこで実行されたか確認する** GitHub の実行ビューで、ジョブのランナー名により、GitHub ホステッドではなく Latchkey のマシンが引き受けたことが確認できます。実行のたびに新しい名前を期待してください: ランナーは設計上、単回使用です。
2. **分数が計上されるのを見る** 移行されたジョブの分数は、プランの無料ティアに対して累積します。課金モーダルは無料ティアの進捗とこれまでの推定コストを表示し、[コスト分析](/documentation/cost-analysis) ページは GitHub の支出と並べて Latchkey ランナーの支出を追跡します。詳細は [ランナーの使用量と無料分](/documentation/runner-usage-and-free-minutes) にあります。

## ロールバック

ロールバックは同じ 1 行の変更を逆方向に行うだけです: 移行 PR をリバートすれば、ジョブは即座に GitHub ホステッドランナーへ戻ります。それ以外に取り消すものはなく、アンインストールするエージェントも、片付ける構成もありません。リポジトリは監視されたままなので、いずれにせよ分析は継続します。

## よくある質問

### シークレットを変更する必要はありますか?

いいえ。GitHub は、GitHub ホステッドランナーの場合とまったく同じように、Latchkey ランナー上でも実行時に Actions のシークレットをジョブに注入します。何も再構成されず、Latchkey がその値を読むことは決してありません。

### actions/cache は引き続き機能しますか?

はい、変わらず機能します。Latchkey ランナー上でより速い保存と復元が必要なら、Latchkey のキャッシュ action (`latchkey-dev/cache-action@v1`) がドロップインのアップグレードです。[依存関係のキャッシュ](/documentation/dependency-caching) を参照してください。

### Latchkey と GitHub ホステッドのランナーを混在させられますか?

はい、自由に、いつまでも。`runs-on` はジョブごとに決定されるため、ワークフロー内の各ジョブは最も適した場所で実行できます。

---

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