2026年2月26日、GitHubはmacOS 26 Runnerが一般提供になったと発表しました。公式Changelogによれば、YAMLを変更していなくても、macos-latestの実体が変わればビルド環境は変化します。
症状：YAMLは同じなのに、Xcode、依存ライブラリ、署名、キャッシュのどこかで失敗する。
最短解決策：まず実際のOS・Runnerアーキテクチャー・Xcodeをログに出し、明示的なmacOSタグで並列検証してから切り替えてください。
この手順は、まだmacos-latestを使い、実際のRunnerイメージを確認していないiOS・macOS開発者向けです。CocoaPods、SwiftPM、Node.js、Ruby、ネイティブバイナリを管理するCI担当者や、長期稼働するMac自前Runnerの導入を判断する開発基盤チームにも適しています。
macOS 26移行の影響を最初のログで判定する
GitHub Actionsのmacos-latestは現在どのシステムなのか。
固定のOS名として推測せず、実行時のログで確認してください。GitHubはラベルの意味と利用可能なRunnerを公開していますが、ラベルとイメージの対応やプリインストールソフトは更新されます。Runnerラベルの公式説明と公式Runnerイメージ一覧を、公開日の設定だけでなく実行日の確認資料として使います。
最初に診断用のジョブを一時的に追加します。
jobs:
inspect:
runs-on: macos-latest
steps:
- name: Inspect runner
run: |
sw_vers
uname -m
xcode-select -p
xcodebuild -version
node --version || true
ruby --version || true
python3 --version || true
brew --version || true
clang --version
このログで、YAMLのラベルではなく、OS、CPUアーキテクチャー、Xcodeのパス、主要ランタイムの実体を記録できます。2026年6月15日から7月15日にmacos-latestをmacOS 26へ移行する計画も公式告知に含まれていたため、その期間の失敗はまずラベル移行と環境差分を照合します。移行告知の記載だけで現在の対応関係を断定せず、macOS 26イメージのREADMEと当日のログを突き合わせてください。
| 確認対象 | まず見る証拠 | 移行時の扱い |
|---|---|---|
| ラベル | runs-onの値と実行ログ |
macos-latestだけで固定済みと判断しない |
| OS・イメージ | sw_vers、イメージREADME |
明示的なOSタグで比較する |
| CPU | uname -m、バイナリ検査 |
Intel向け依存を個別に検証する |
| Xcode | xcode-select、xcodebuild -version |
パスとバージョンをJob内で固定する |
| キャッシュ | キー、復元結果、保存結果 | OS・CPU・ツールチェーン差をキーに含める |
macOS 15のワークフローはmacOS 26へ移行すべきか。
テスト用の無状態Jobなら、明示的なmacOS 26タグとの並列実行で互換性を確認してから移行できます。一方、Appleプラットフォームのアーカイブ、配布、署名を含むJobは、検証が終わるまでmacOS 15相当の既存環境を回退経路として残すべきです。
| ワークロード | 先に取るべき方針 | 合格条件 |
|---|---|---|
| 単体テスト・静的解析 | macOS 26と旧環境を並列実行 | テスト結果と依存復元が一致する |
| iOS・macOSビルド | XcodeとSDKを明示して検証 | 生成物、テスト対象、警告を比較できる |
| リリース署名・アーカイブ | 既存Jobを直ちに上書きしない | 署名検証と回退演習が完了している |
XcodeとSDKの差分を失敗箇所から切り分ける
macOS 26 Runnerの更新後にビルドが失敗した場合、何から確認するか。
まず、Xcodeの選択を省略していないか確認します。xcode-select -pだけでなく、xcodebuild -version、SDK一覧、対象シミュレーターをログへ出し、AppleのXcodeシステム要件とRunnerイメージの記載を照合します。
典型的な症状は、次のように分類できます。
- コンパイルエラー：旧SDKの挙動や非推奨APIを前提にしたコードを疑います。
- リンクエラー：Framework、SwiftPM成果物、CocoaPodsのバイナリが新しいSDKやCPUに対応しているか確認します。
- テスト起動失敗：指定したシミュレーターのOSと、Runnerに存在するランタイムが一致しているか調べます。
- 署名・アーカイブ失敗：証明書、プロビジョニングプロファイル、キーチェーンの作成手順をOS更新と分離して再実行します。
次の順番で移行します。
- macOS 26と既存の明示的なmacOSタグに同じコミットを投入します。
xcode-selectで利用するXcodeパスを選択し、選択結果をログに保存します。- SDK、シミュレーター、SwiftPMまたはCocoaPodsの解決結果を記録します。
- コンパイル、テスト、アーカイブ、署名を別Jobに分けます。
- 署名を伴わない検証が通った後に、配布用Jobを実行します。
- 旧タグで再実行できる回退用Jobを残します。
Xcode 27など、安定版として正式に提供されているか確認できないツールチェーンは、現行の本番環境と混同しないでください。テスト段階の設定を採用する場合は、Job名と成果物を本番系から分離します。
Apple SiliconとIntel依存を4種類に分けて調べる
Apple Silicon対応を「コンパイルが成功した」という一言で判断するのは危険です。GitHubの自前Runner資料でも、ラベル、OS、アーキテクチャーは別の選択要素として扱われています。自前Runnerの公式仕様を確認し、実行対象のCPUでテストしてください。
| 依存の種類 | 見える症状 | 検証方法 |
|---|---|---|
| 事前ビルドバイナリ | 実行時にCPU不一致やロード失敗 | file、lipo -infoで形式を確認 |
| ネイティブ拡張 | npm、Ruby、Python依存のビルド失敗 | 再ビルドログとコンパイラーを確認 |
| スクリプトの判定 | CPU名の条件分岐が誤動作 | uname -mを出力して分岐を追う |
| 生成物の互換性 | 別CPUで実行すると失敗 | 実際の対象アーキテクチャーでテスト |
arm64向けにビルドできても、Intel環境で動く証明にはなりません。反対にx86_64のツールをRosetta経由で動かせても、ネイティブ依存がApple Siliconで正常に動くとは限らないため、ビルドと実行を同じCPU条件で分けて記録します。
ランタイム、キャッシュ、署名を独立した検証対象にする
macOS 26への移行で、すべてのスクリプトエラーをOSのせいにしてよいか。
いいえ。Node.js、Ruby、Python、Homebrew、Clang、OpenSSLの差異、Actionの更新、プロジェクト側の依存固定不足を分離してください。各Jobの冒頭でバージョンと実行ファイルのパスを出し、最小の再現Jobを作ります。
特にキャッシュは、古いOSやCPUで作成した成果物を新しい環境へ復元している可能性があります。GitHub Actionsの依存キャッシュ仕様に沿って、OS、アーキテクチャー、Xcode、ロックファイルのハッシュをキャッシュキーに含め、初回はキャッシュなしでも成功するか確認します。
署名Jobでは、次を別々に確認します。
- 証明書とプロファイルが想定した対象へ入っているか。
- 一時キーチェーンを作成する順番が変わっていないか。
security find-identityとアーカイブ後の署名検証結果が一致するか。- ログに秘密情報や署名関連の機密値が出ていないか。
ここまでの検証結果は、SSHMacのヘルプセンターにある運用上の確認項目とも照合できます。自前Runnerを追加する場合は、登録トークン、私有リポジトリへのアクセス権、Runner更新を分離し、公式のRunner登録と安全対策に従って権限を最小化してください。
判定結果を3段階の移行条件へ落とし込む
次の条件分岐で、タグ変更を一度に本番へ反映するかを決めます。
- 無状態のテストが中心で、macOS 26と既存環境のテスト結果が一致する場合：明示的なmacOS 26タグへ移行します。
macos-latestは将来の自動移行を受けるため、再現性が必要なJobでは避けます。 - Xcode、SDK、ネイティブ依存の差分が残る場合：OSタグとXcodeを固定し、依存更新またはスクリプト修正を先に行います。リリースJobは旧環境へ回退できる状態を保ちます。
- 固定ツールチェーン、署名ID、持続キャッシュが不可欠な場合：独立したMac自前Runnerを追加します。ホステッドRunnerとの併用にし、単一障害点にしない構成が適切です。
- 物理USB、特定の周辺機器、長時間の固定処理が必要な場合：レンタルや自前Runnerの接続条件を先に確認します。ホステッドRunnerだけで代替できない可能性があります。
合格とする証拠は、単発の成功では足りません。連続したビルド結果、生成物の比較、署名検証、キャッシュ有無での再実行、旧環境への回退演習を記録してください。自前Runnerは安定性だけを理由に無制限の権限を与えず、リポジトリ分離、秘密情報の扱い、更新確認、利用後のワークスペース消去を運用に組み込みます。
ホステッドRunnerは毎回クリーンな環境で走る短時間のテストには扱いやすい一方、イメージ変更、依存の再取得、署名環境の再構築が発生します。固定Xcodeや長期キャッシュを優先するなら、SSHMacのMacレンタルプランで独立したMac環境を確保し、GitHub Actionsの自前Runnerとして使う方法を検討できます。
最終的には、環境差分を許容できるテストは明示タグ付きのホステッドRunner、署名と固定ツールチェーンを重視するリリースは管理可能なMacノード、という分担が現実的です。SSHMacのリモートMacを使う場合も、まず必要なXcode、CPU、接続方法、契約期間、アクセス権限を確認し、短期検証ならレンタル、長期の安定負荷なら自社保有を含めて比較してください。
最終更新：2026年8月23日。タグ対応、macOS 26イメージ、Runner仕様はGitHub Changelog、GitHub Docs、runner-images、Appleの公式資料を基に確認しています。公開時には診断Jobの実行ログで再確認してください。