--- title: "GitHub Actionsのruns-on｜ラベル指定の記法と-latest更新・arm64への備え" url: "https://www.issoh.co.jp/tech/details/16929/" published: 2026-08-25 updated: 2026-09-27 categories: ["GitHub"] publisher: "株式会社一創" --- # GitHub Actionsのruns-on｜ラベル指定の記法と-latest更新・arm64への備え `runs-on`は、そのジョブをどのマシンで走らせるかを決める一行です。書き方自体は数分で覚えられますが、`ubuntu-latest`のまま放置したチームは、GitHubがイメージを入れ替えた月に前触れなくビルドが落ちる経験をします。逆にすべてを固定バージョンで書けば、今度は古いイメージの提供終了に追われる形になるでしょう。この記事では、記法の全体像、2026年8月時点のラベル一覧、イメージ更新への備え、ジョブが無言で止まる事故の切り分け、切り替え条件をまとめました。ワークフローの基本構造は[GitHub Actionsとは？できること・使い方とCI/CD自動化の解説記事](https://www.issoh.co.jp/column/details/3005/)、発火条件の設計は[GitHub Actionsのトリガー（on）｜イベント選定とbranches・pathsフィルタの設計](https://www.issoh.co.jp/tech/details/16923/)を参照してください。 ## まとめ：runs-onのラベル選択で押さえる4つの判断 第一に、`runs-on`は文字列・配列・`group`付きオブジェクトの3つの形を取り、配列はOR条件ではなくAND一致です。`[self-hosted, linux, x64]`と書けば、3つのラベルを全て持つランナーだけが対象になります。第二に、`-latest`は固定バージョンではなく別名で、新しいOSがGAになると1〜2か月かけて段階的に指し先が入れ替わる仕様です。2026年8月時点で`ubuntu-latest`は`ubuntu-24.04`、`windows-latest`は`windows-2025`、`macos-latest`は`macos-26`を指しています。 第三に、リリース物を作るジョブとリンターのような使い捨てジョブでは、固定するかどうかの判断を変えてください。前者はバージョンを打って再現性を取り、後者は`-latest`に乗せるほうが移行の痛みが分散します。第四に、ラベルが1文字でも噛み合わないジョブはエラーにならず、キューに座り続けたまま24時間後に自動キャンセルされます。CIが赤くならないので気づきにくく、セルフホストを混ぜた組織で最も多い無音故障です。 ## GitHub Actionsのruns-onが受け取る3つの記法を整理する `runs-on`はジョブ単位のキーで、書ける形は3種類あります。GitHubが用意したランナーを使うのか、自前のマシンを絞り込むのか、組織で切ったランナーグループを指すのかで決まります。いずれの形にも式を差し込めば実行時に切り替えられる点は共通です。 ### 文字列1つでGitHub-hostedランナーを直接指定する書き方 最も短い形が、ラベルを1つだけ書くものです。GitHub-hostedなら足ります。 ``` jobs: build: runs-on: ubuntu-24.04 steps: - uses: actions/checkout@v5 - run: npm ci && npm test ``` ここで指定した文字列は、GitHubが公開しているラベルの集合と照合されます。存在しない綴りを書いても構文検証は通ってしまう場面があるため、ラベル名は次章の一覧から写すのが安全です。この位置に書けるのはラベルであってOS名ではなく、`ubuntu`のような表記は一致しません。 ### 配列で書いた複数のラベルはAND一致で対象ランナーを絞り込む 配列にすると、指定した全てのラベルを持つランナーが対象になります。公式ドキュメントは「指定した値すべてに一致するランナーで実行される」と明記しており、いずれか1つに当たれば良いという挙動ではありません。主にセルフホストの絞り込みで使う記法です。 ``` jobs: gpu-test: runs-on: [self-hosted, linux, x64, gpu] steps: - run: nvidia-smi ``` `self-hosted`・OS・アーキテクチャの3つは登録時に自動で付与される既定ラベルで、`gpu`のような任意ラベルは管理画面かコマンドで足します。絞り込みを強くするほど候補ランナーは減り、該当が1台もなければジョブは待ち続けます。ラベル設計とランナー登録の手順は[GitHubセルフホストランナーとは？導入手順とhosted版の違い](https://www.issoh.co.jp/tech/details/7759/)にまとめました。 ### groupとlabelsのオブジェクト記法でランナーグループを指す 組織やEnterpriseでランナーグループを切っているなら、グループ名とラベルを併記できます。どのプールから取るかを明示できるのが利点です。 ``` jobs: build: runs-on: group: ubuntu-runners labels: ubuntu-24.04-16core ``` `group`だけを書けばそのグループ内の空きランナーへ、`labels`を併記すればさらにラベル一致まで求めます。大型ランナーも静的IPを持つランナーも実体はグループ経由で配られるため、この記法が入口です。`labels`には配列も渡せます。 ### 式でランナーを動的に切り替えるときの引用符とfromJSON `runs-on`の値には式を書けます。手動実行の入力でランナーを選ばせる構成が典型です。入力の型定義と起動方法は[GitHub Actionsの手動実行（workflow\_dispatch）｜inputsの型定義とCLI・APIからの起動](https://www.issoh.co.jp/tech/details/16931/)で解説しています。 ``` on: workflow_dispatch: inputs: chosen-os: required: true type: choice options: [ubuntu-24.04, macos-15] jobs: test: runs-on: "${{ inputs.chosen-os }}" ``` ここで引っかかりやすいのが引用符です。公式ドキュメントは「`self-hosted`のような単純な文字列には引用符は不要だが、式には必要」と述べています。裸の波括弧はYAMLのフロースタイル開始と読まれるため、式は必ずクォートで囲んでください。複数ラベルを実行時に渡したいときは、文字列としてのJSON配列を`fromJSON`で配列へ戻します。`runs-on: ${{ fromJSON(inputs.runner-labels) }}`と書けば、渡したラベル配列がそのままAND条件として扱われる形です。`vars`を参照すれば、リポジトリ変数の書き換えだけでランナーを切り替えられるため、ワークフローファイルへ手を入れずに移行を試せます。変数の置き場所と受け渡しは[GitHub Actionsの環境変数｜env・vars・secretsの使い分けと受け渡し](https://www.issoh.co.jp/tech/details/16921/)で整理しました。 ### matrixと組み合わせて複数のOSを1つのジョブ定義で回す 同じ処理を複数OSで走らせるときは、`strategy.matrix`で値を並べて参照します。 ``` jobs: test: strategy: fail-fast: false matrix: os: [ubuntu-24.04, windows-2025, macos-15] runs-on: ${{ matrix.os }} ``` この形なら1つのジョブ定義で3並列になります。マトリクスは1回の実行で最大256ジョブまで展開できますが、OSを増やすほど分単価の高い枠を踏むため、全ジョブのマトリクス化は避けてください。実務では単体テストだけ3OS、ビルドと配布はLinux単体、という切り分けに落ち着きます。 ## 2026年8月時点のGitHub-hostedランナーのラベル一覧 ラベルは増減します。以下は2026年8月時点の公式リファレンスから写した現行ラベルで、preview表記のものは本番のリリース経路には入れないでください。 | 系統 | 既定線のラベル | 併存するラベル | | ------------- | ---------------- | ------------------------- | | Linux x64 | ubuntu-latest | ubuntu-24.04／ubuntu-22.04 | | Linux arm64 | ubuntu-24.04-arm | ubuntu-22.04-arm | | Linux 軽量 | ubuntu-slim | なし | | Linux preview | ubuntu-26.04 | ubuntu-26.04-arm | | Windows x64 | windows-latest | windows-2025／windows-2022 | | Windows arm64 | windows-11-arm | windows-11-vs2026-arm | | macOS arm64 | macos-latest | macos-15／macos-14 | | macOS Intel | macos-26-intel | macos-15-intel | ### Linuxはx64とarm64とubuntu-slimの3系統に分かれる Linuxは同じUbuntuでも3つの系統があります。x64の通常イメージが既定線で、`-arm`接尾辞が付いたものがarm64、そして`ubuntu-slim`が軽量枠です。`ubuntu-slim`は1コア5GBのコンテナ実行で、実行時間の上限や不足するプリインストールツールなど独自の制約を持ちます。静的解析やラベル付けのような短いジョブを寄せる先として設計された枠のため、通常のビルドを移すと逆に失敗率が上がる点に注意が要ります。スペック差と適用条件は[GitHub Actionsの低コストな軽量ランナー『Ubuntu-slim』とは？概要と特徴を解説](https://www.issoh.co.jp/tech/details/9661/)で個別に扱いました。 ### WindowsとmacOSはアーキテクチャの世代交代が進んでいる Windowsは`windows-2025`が現行で、Visual Studio 2026を積んだ`windows-2025-vs2026`が別ラベルとして併走しています。macOSはarm64が既定線になり、Intelは`-intel`接尾辞の別ラベルへ切り出されました。つまり`macos-latest`とだけ書いたジョブは、いつの間にかapple silicon上で動いています。この差は成果物のアーキテクチャに直結するので、配布物があるなら`macos-15`のように世代を打つほうが安全です。 ### 同じラベルでもパブリックとプライベートで標準スペックが2倍違う 見落とされやすいのがスペック差です。公式リファレンスによると、標準のLinux x64およびWindowsランナーは、パブリックリポジトリでは4コア16GB、プライベートでは2コア8GBになります。SSDはいずれも14GBです。macOSのarm64は3コア7GBで、両者に差がありません。OSSで通っていたビルドをそのまま社内のプライベートリポジトリへ持ち込むとメモリ不足で落ちる、という事故はこの差から生まれます。移設時はまずコア数とメモリを疑ってください。 ## \-latestラベルが動く前提でランナー更新の破壊的変更に備える `-latest`はバージョンではなく別名です。ランナーイメージのリポジトリは、ラベルの移行が利用者の適応期間として1〜2か月かけて段階的に行われると説明しています。この期間中、同じ`ubuntu-latest`と書いたジョブが実行ごとに新旧どちらへ当たるか分かりません。イメージ自体もおよそ週次で更新されます。 ### ubuntu-latestが24.04へ移った時に何が壊れたのかを振り返る 直近で影響が大きかったのが、`ubuntu-latest`が22.04から24.04へ移った局面です。Python 2が消え、OpenSSLが3系になり、プリインストールのNode.jsの既定が18から20へ上がりました。Terraform、Heroku CLI、Netlify CLI、Vercel CLIはイメージから外れています。さらに24.04ではpipでシステム全体へパッケージを入れる操作が制限されました。`setup-node`を使わずPATH上のnodeに任せていたワークフローは、何も変更していないのにNodeの世代が上がります。教訓は単純で、ランタイムはイメージ任せにせず`setup`系のアクションでバージョンを明示する、という一点に尽きます。 ### \-latestの移行は1〜2か月かけて段階的に進む仕様である 移行が一斉に切り替わらないのは救いでもあり、厄介でもあります。段階移行の最中は、同じワークフローが日によって成否を変える不安定さが出ます。切り分けのコツは、失敗したジョブのログ冒頭に出るランナーイメージのバージョン行を見比べることです。新旧が混在していれば移行期に当たっています。この期間は、影響の大きいジョブだけ`ubuntu-22.04`のように旧世代を打って足場を固める進め方が現実的でしょう。 ### windows-11-armが2026年9月初旬にvs2026イメージへ移る 直近で控えている切り替えも押さえておきます。2026年6月11日のGitHub Changelogは、`ubuntu-26.04`・`ubuntu-26.04-arm`・`windows-11-vs2026-arm`のpublic previewを告知したうえで、プレビュー終了時である2026年9月初旬に、既存の`windows-11-arm`ラベルがvs2026イメージへ移行すると明記しました。Windows arm64でビルドしているチームは、ラベルを書き換えていなくてもツールチェーンが入れ替わります。Visual Studioの世代に依存したビルドがあるなら、9月を待たず`windows-11-vs2026-arm`で先に通しておくのが安全です。`ubuntu-26.04`側は移行時期が公表されていませんが、previewが立った以上は次の対象と見て準備を始める段階にあります。 ### バージョンを固定するジョブと固定しないジョブの線引きを決める 全部固定は運用が重く、全部`-latest`は事故が読めません。線引きの基準を条件で置きます。リリース成果物を生成するジョブ、コンパイル済みバイナリを配るジョブ、環境差が再現性に直結するE2Eジョブは固定側です。リンター、フォーマッタ、ドキュメント生成、脆弱性スキャンは`-latest`側に置き、更新の当たりを早く受けます。固定側は四半期に一度まとめて世代を上げる棚卸しをセットにしてください。棚卸しのない固定は、提供終了の通知が来た週に全ジョブが一斉に止まる形へ変わります。 ## runs-onのラベル不一致でジョブが止まる典型と切り分け方 ラベル指定の失敗は例外を投げません。該当ランナーが見つからないジョブは、単に待ち状態のまま置かれます。ステータスは赤にならず失敗通知も飛ばないため、リリース当日に気づく形です。 ### セルフホストのラベル綴り違いでジョブが永久にqueuedになる 最も多いのが綴りとケースの不一致です。ランナー側に`Linux`と登録されているのに`linux`と書く、`x64`と`amd64`を取り違える、といった差でAND一致は崩れます。切り分けの手順は決まっています。まず設定画面でランナー一覧を開き、付与されているラベル文字列をコピーしてください。次にワークフローの配列と一字ずつ突き合わせます。オフラインなだけの場合も同じ症状になるため、状態表示も同時に確認します。 ### キューは24時間で自動キャンセルされるため検知の仕組みを作る 公式のリミット一覧は、ジョブがキューに入れる時間を24時間とし、超えると自動的にキャンセルされると定めています。実行時間そのものの上限はGitHub-hostedで6時間、ワークフロー全体で35日です。注意したいのが`timeout-minutes`で、キュー待ちではなく実行時間に効くため滞留は止められません。滞留を捕まえるなら、待機中のジョブ数を定期的にAPIで拾って閾値超過を通知する仕組みを別に置いてください。 ### previewラベルは容量が偏るためキュー待ちが伸びる前提で使う previewのラベルは、GitHub側も容量の平準化が数週間かかると説明しています。実際、preview期間中は同じ設定でもピーク時間帯に待ち時間が伸びます。新しいイメージを試すジョブは検証用ワークフローへ切り出し、夜間の定期実行で回してください。本番のブロッキングチェックへ入れると、待ち時間の揺れがマージ速度の揺れになります。 ### matrixで存在しないラベルを組み立ててしまう事故を防ぐ書き方 マトリクスでOS名とバージョンを文字列結合してラベルを作る書き方は、一見きれいですが壊れやすい構成です。片方の値を足した瞬間に存在しないラベルが生まれます。実在するかは実行時まで判明せず、失敗ではなく待機になるため発見も遅れます。マトリクスには完成したラベル文字列を並べ、`include`で例外を足してください。ラベルは組み立てず、書き写す。この一行を規約にするだけで事故はほぼ消えます。 ## 標準ランナーからarm64・大型・セルフホストへ移す判断条件 ここからは判断の話です。選択肢は標準・軽量・arm64・大型・セルフホストの5段階あり、上へ行くほど速くなる代わりに費用か運用負荷が乗ります。どこで線を引くかは条件で言い切る形にしました。なお分単価や無料枠の実数は[GitHub Actionsの料金｜2026年改定後の分単価・無料枠とコスト削減の判断基準](https://www.issoh.co.jp/tech/details/16698/)に集約してあるため、本記事では金額そのものではなく切り替えの条件だけを扱います。 ### 標準のubuntu-latestのままで足りるジョブの条件を先に決める 次の3条件を全て満たすなら、標準ランナーから動かす必要はありません。ジョブの実行時間が10分以内に収まっていること、並列数が契約プランの同時実行上限に達していないこと、ビルドがネイティブ拡張やGPUに依存していないこと。この範囲ではランナーを上げても短縮は数分どまりで、待ち時間の大半はキャッシュの復元とチェックアウトが占めます。先にキャッシュ設計を見直すほうが効きます。key設計と復元されない原因の切り分けは[GitHub Actionsのキャッシュ｜actions/cacheのkey設計と復元されない原因の切り分け](https://www.issoh.co.jp/tech/details/16933/)にまとめてあります。 ### arm64のランナーへ寄せてよい条件と避けるべき条件を分ける arm64へ寄せてよいのは、スクリプト言語のテスト、コンテナイメージのマルチアーキテクチャビルドの片翼、Goのようにクロスコンパイルが素直な言語のビルドです。x64より分単価が下がる枠であり、CPU律速のジョブでは所要時間も縮みます。避けるべきなのは、x64前提のバイナリを直接落とすステップを含むジョブ、プロプライエタリなエージェントを入れているジョブでしょう。判定は簡単で、既存のワークフローを`ubuntu-24.04-arm`へ向けて1回流し、落ちたステップを数えてください。1つか2つなら移す価値があり、半分落ちるなら見送りです。 ### 大型ランナーへ切り替える判断は待ち時間と分単価の交換で決める 大型ランナーは組織設定で作り、名前がそのままラベルになります。作成時にサイズとプラットフォームを選び、ランナーグループへ割り当てて、リポジトリからは`runs-on`のグループ指定かラベル指定で参照する流れです。静的IPを割り当てられる点も、社内APIへ疎通させたい案件では効きます。ランナーの選択と併せて、反映先ごとに資格情報と承認を分ける設計は[GitHub ActionsのEnvironments｜承認ゲートと環境別シークレットの設計](https://www.issoh.co.jp/tech/details/16935/)を参照してください。切り替えの条件は、ジョブがCPUまたはメモリで律速していると計測で確認できていること、この1点に絞ってください。コア数を倍にしても短縮しないジョブは、入出力かネットワークで待っています。逆にコンパイルがコア数へ比例して縮むジョブなら、分単価が上がっても総分数が減って費用は横ばいになり得ます。大型ランナーの分が無料枠の対象外という点だけ、見積もりの前提に入れておきましょう。 ### セルフホストへ出す条件は依存と隔離とキュー滞留の3点で決める セルフホストへ出す判断は、費用ではなく制約で決めます。3つのうちどれかに当たれば検討に値します。第一に、社内ネットワークの内側にしかない資源へ到達する必要があるとき。第二に、特殊なハードウェアや商用ライセンスを固定マシンに縛る必要があるとき。第三に、同時実行上限に張り付いていてキュー滞留が慢性化しているとき。ただし滞留の原因がグループ内の待機なら、ランナーを増やす前に[GitHub Actionsのconcurrency｜groupの設計とcancel-in-progress・queueの選び方](https://www.issoh.co.jp/tech/details/16945/)の側で解けます。どれにも当たらないなら、マシンの維持、ランナーの更新、ジョブ間の汚染対策という運用が丸ごと乗るだけです。導入の手順とラベル設計は[GitHubセルフホストランナーとは？導入手順とhosted版の違い](https://www.issoh.co.jp/tech/details/7759/)にまとめました。ランナー構成はCI/CD全体の設計と切り離せないため、パイプラインそのものの組み立てから見直すなら[CI/CDとは？仕組み・パイプライン・導入すべき企業の判断基準を解説](https://www.issoh.co.jp/column/details/13002/)も併せて確認してください。ランナー更新への追随、イメージ移行時の一斉修正、セルフホストの維持まで含めて外部へ預けたい場合は、[保守運用 / 内製化支援](https://www.issoh.co.jp/service/system/maintenance/)で既存のCI基盤ごと引き取り、社内で回せる状態まで移す支援を行っています。 ## よくある質問 ### runs-onに変数を直接書けますか？ 書けます。`inputs`・`vars`・`matrix`のいずれも参照でき、実行時にランナーが決まります。ただし式は必ず引用符で囲んでください。複数ラベルを渡す場合は`fromJSON`で配列へ戻します。`secrets`コンテキストはこの位置では扱えません。 ### ubuntu-latestとubuntu-24.04はどちらを書くべきですか？ ジョブの性格で分けます。リリース成果物を作るジョブは`ubuntu-24.04`のように固定し、リンターやドキュメント生成は`ubuntu-latest`で構いません。固定した場合は四半期に一度の棚卸しを予定へ入れてください。 ### arm64のランナーに切り替えるとテストは壊れますか？ ステップ次第です。x64のバイナリを直接ダウンロードするステップ、アーキテクチャ固有のネイティブ拡張をビルドするステップが主な失敗要因になります。判定は`ubuntu-24.04-arm`で1回流し、落ちた数を数えるのが早い方法です。 ### 大型ランナーのラベルはどこで作りますか？ 組織またはEnterpriseの設定画面から作成し、サイズとプラットフォームを選んでランナーグループへ割り当てます。作成時に付けた名前がそのままラベルです。ワークフロー側は`group`と`labels`を併記する記法で参照するのが確実になります。 ### ジョブがずっとqueuedのまま動きません。何を見ればよいですか？ まず設定画面のランナー一覧を開き、指定した全ラベルを持つランナーが実在してオンラインかを確認します。セルフホストなら綴りとケースの不一致が最有力です。GitHub-hostedなら同時実行上限に張り付いていないか、previewラベルを踏んでいないかを見てください。 ## 関連記事 - [GitHubセルフホストランナーとは？導入手順とhosted版の違い](https://www.issoh.co.jp/tech/details/7759/)：ランナー登録とラベル付与の実務手順です。 - [GitHub Actionsの低コストな軽量ランナー『Ubuntu-slim』とは？概要と特徴を解説](https://www.issoh.co.jp/tech/details/9661/)：軽量枠へ寄せられる条件を確認できます。 - [GitHub Actionsの料金｜2026年改定後の分単価・無料枠とコスト削減の判断基準](https://www.issoh.co.jp/tech/details/16698/)：ランナー選択の費用影響を実額で確かめられます。 - [GitHub Actionsのトリガー（on）｜イベント選定とbranches・pathsフィルタの設計](https://www.issoh.co.jp/tech/details/16923/)：どのイベントでジョブを起こすかの設計はこちらです。 - [GitHub Actionsの環境変数｜env・vars・secretsの使い分けと受け渡し](https://www.issoh.co.jp/tech/details/16921/)：varsで切り替える前提の知識が揃います。 - [GitHub Actionsとは？できること・使い方とCI/CD自動化の解説記事](https://www.issoh.co.jp/column/details/3005/)：基本構造から確認したい場合の入口です。 - [CI/CDとは？仕組み・パイプライン・導入すべき企業の判断基準を解説](https://www.issoh.co.jp/column/details/13002/)：ランナー構成を含む全体設計の前提を整理できます。 --- 出典: [GitHub Actionsのruns-on｜ラベル指定の記法と-latest更新・arm64への備え]()（株式会社一創）