ドキュメントメニュー
マネージドランナー
ワークフローファイル
GitHub ホステッドランナーからの移行
完全な移行ガイド: 実際に何が変わるか、3 つの移行パス、Migrate Runners ツールが適用する正確なラベルマッピング、PR に含まれる内容、検証、そしてロールバック。
要点
- 変わるのは
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-* ラベルと並行して機能し続けるため、完全な切り替えを強いられることはありません。
何が変わり、何が機能し続けるか#
- 移行する各ジョブの
runs-on:ラベル
- マーケットプレイスおよびカスタムの actions
- リポジトリ、environment、組織の シークレット
- Environments とその保護ルール
actions/cacheを含む、GitHub 側に保存されたキャッシュ
始める前に#
移行する 3 つの方法#
3 つのパスは組み合わせられます: ほとんどのチームは、パイロットとして 1 つのワークフローを手動で編集し、ツールで一括移行し、独自のイメージに値する少数のリポジトリには AI Scan を使います。
| パス | 適した用途 |
|---|---|
| Migrate Runners ツール | 一括移行: 1 回のパスで最大 20 の監視対象リポジトリ、それぞれにレビュー可能な PR を 1 つ |
runs-on: の手動編集 | 単一のワークフロー、パイロットジョブ、またはツールが認識しないラベル |
| AI Scan | プリセットではなく、適切なサイズのカスタムイメージに値するリポジトリ |
パス 1: Migrate Runners ツール#
Runners ページに Runner types パネルが表示され、そのフッターには「Already have workflows on GitHub-hosted runners? Migrate them to Latchkey runners in a few clicks.」とあり、横に Migrate runners ボタンがあります。暗くなったページの上に Migrate runners ダイアログが開きます。「Pick the monitored repos you want to migrate. We'll open one PR per repo that swaps every supported runs-on: label to a Latchkey runner. Anything we can't map (Windows, exotic self-hosted) is left untouched.」監視対象の 3 つのリポジトリ acme/api、acme/web、acme/worker が並び、選択は 0/20 です。acme/api を選ぶと 1/20 になりボタンは Open migration PR、続いて acme/web を選ぶと 2/20 になりボタンは Open migration PRs になります。ボタンを押すと Opening PRs… と表示され、その間ダイアログの閉じるボタンは待機します。ダイアログは「Opened 2 pull requests. Merge each on your schedule.」で終わり、acme/api #431 と acme/web #92 がそれぞれ View PR 付きで並びます。
このツールには 2 つの入口があり、どちらも同じダイアログを開きます: Runners ページ の Runner types パネルのフッターにある Migrate runners と、Settings の Code hosts タブの Repositories パネルにある Migrate runners です。移行 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 行で、どちらのラベル形式も同じようにルーティングされます:
jobs: test: runs-on: latchkey-small
jobs: test: runs-on: [self-hosted, latchkey-small]
最初の実行の検証やサイズの選択を含む、このパスのステップバイステップ版は 最初のジョブを実行する です。
パス 3: AI Scan、独自のイメージに値するリポジトリ向け#
一部のリポジトリはラベルの置き換え以上の価値があります。AI Scan はリポジトリが実際に実行するワークフローを読み取り、適切なサイズの形状と、リポジトリのツールチェーンをプリインストールするイメージを備えたカスタムランナー構成を提案します。これによりジョブはセットアップステップを丸ごとスキップできます。心当たりのあるリポジトリがあれば、AI Scan によるカスタムランナー から始め、そのリポジトリをプリセットではなくカスタムラベルに移行してください。
段階的な戦略#
一括移行は必要なく、避けることをお勧めします。低リスクのリポジトリ 1 つ、理想的には、安い分、速いピックアップ、自己修復が最も見えやすい不安定または遅いリポジトリから始め、フリート全体を移す前に 1 週間実行させてください。
GPU、Windows、macOS、arm64 ホストを必要とするジョブは GitHub ホステッドや他のランナーに留まり、それはいつまでもそのままで問題ありません: runs-on はジョブごとに決定されるため、ワークフローは Latchkey と GitHub ホステッドのジョブを自由に混在させられます。
マージ後に検証する#
GitHub の実行ビューで、ジョブのランナー名により、GitHub ホステッドではなく Latchkey のマシンが引き受けたことが確認できます。実行のたびに新しい名前を期待してください: ランナーは設計上、単回使用です。
移行されたジョブの分数は、プランの無料ティアに対して累積します。Billing ページは無料ティアの進捗とこれまでの推定コストを表示し、Cost ページは Latchkey ランナーの支出を追跡します。詳細は ランナーの使用量と無料分 にあります。
ロールバック#
ロールバックは同じ 1 行の変更を逆方向に行うだけです: 移行 PR をリバートすれば、ジョブは即座に GitHub ホステッドランナーへ戻ります。それ以外に取り消すものはなく、アンインストールするエージェントも、片付ける構成もありません。リポジトリは監視されたままですが、ダッシュボードには Latchkey が処理したジョブだけが表示されるため、GitHub ホステッドランナーへ戻ったジョブはそこに表示されなくなります。
よくある質問#
Q.01シークレットを変更する必要はありますか?
いいえ。GitHub は、GitHub ホステッドランナーの場合とまったく同じように、Latchkey ランナー上でも実行時に Actions のシークレットをジョブに注入します。何も再構成されず、Latchkey がその値を読むことは決してありません。
Q.02actions/cache は引き続き機能しますか?
はい、変わらず機能します。Latchkey ランナー上でより速い保存と復元が必要なら、Latchkey のキャッシュ action (latchkey-dev/) を使います。actions/cache の代わりに restore ステップと save ステップを置き、それぞれに path と key の入力を指定します。依存関係のキャッシュ を参照してください。
Q.03Latchkey と GitHub ホステッドのランナーを混在させられますか?
はい、自由に、いつまでも。runs-on はジョブごとに決定されるため、ワークフロー内の各ジョブは最も適した場所で実行できます。