2026年5月14日、GitHubはActionsのイメージ移行に関する公式告知を公開しています。公式告知が示す通り、macos-latest の名前だけでは実行環境を固定できません。今週は再実行や一括アップグレードを先に行わず、Set up job の実環境を記録し、短期は検証済みタグ、長期は管理可能なリモートMac自前Runnerを条件付きで選んでください。

この記事は、iOS・macOSのビルド、テスト、リリースを運用している開発者向けです。GitHub Actions Runnerの選定と環境管理を担当するDevOpsエンジニア、署名資産や永続キャッシュを扱うプラットフォームチームにも適しています。

最終更新：2026年8月21日。ラベル、イメージ、Xcodeの確認は GitHub-hosted runnerの公式リファレンス、runner-imagesのmacOS 26一覧、Apple公式文書を基準にしています。

最初の分岐：コード回帰か環境漂移か

「コードを変更していないのに突然失敗した」という事実だけでは、イメージ更新が原因とは断定できません。まず成功した実行と失敗した実行の Set up job を保存し、実際のOS、イメージ識別子、CPUアーキテクチャ、Xcode、SDK、主要ツールの差分を並べます。

ワークフローに次の診断を一時的に追加すると、ラベル名に頼らず証拠を取れます。

- name: Record build environment
  run: |
    sw_vers
    uname -m
    xcode-select -p
    xcodebuild -version
    xcrun --sdk iphoneos --show-sdk-version
    brew --prefix || true
    ruby --version
    node --version
    python3 --version

実際に使われた環境の記録は、GitHub Actionsの変数に関する公式文書と併せて保管してください。環境情報が同じならコミット差分、ロックファイル、秘密情報の注入を先に調べます。環境情報が変わっていれば、次の4層へ進みます。

CPUアーキテクチャ：ARMとIntelの依存関係

ARMとIntelの違いは、runnerラベルを見ただけでは証明できません。uname -m で実行CPUを確認し、失敗した実行ファイルには file path/to/binary、Homebrewには brew --prefix を使い、OS、実行ファイル、パッケージの3点で証拠をつなげます。

典型的な兆候は、ネイティブNode.jsモジュールのロード失敗、Ruby Gemの拡張ビルドエラー、Homebrew由来ライブラリのリンクエラー、古いキャッシュから復元した異なるアーキテクチャの成果物です。キャッシュを消すだけでなく、対象アーキテクチャで依存関係を再構築してください。

  • [ ] uname -m の結果を成功時と失敗時で比較する
  • [ ] 問題のバイナリを file で調べ、対応するアーキテクチャを記録する
  • [ ] brew --prefix とインストール先を確認する
  • [ ] キャッシュキーにOS、CPU、Xcodeの識別子を含める
  • [ ] 依存関係を対象runner上で再生成する
  • [ ] 固定ラベルでクリーンビルドとキャッシュビルドを両方実行する

既存のIntel用バイナリを維持する必要があるなら、検証済みのIntelラベルを固定します。ARMでの再構築が可能で、依存関係も対応済みならARMを選べますが、ラベル名だけで切り替えないことが重要です。

XcodeとSDK：選択ミスと未対応を分離

Xcodeの問題は、「インストールされていない」「存在するが選択されていない」「選択した版ではプロジェクトが未対応」の3つに分けます。xcode-select -p、xcodebuild -version、xcrun --sdk iphoneos --show-sdk-version、利用可能なシミュレーター一覧を同じログに残してください。

Appleの Command Line Tools設定に関する公式文書でDeveloper Directoryの扱いを確認し、runner-imagesの macOS 26イメージ一覧で、その時点のXcodeとSDKを照合します。イメージの内容は永久保証ではないため、プロジェクトが必要とする版を明示的に選択し、更新用の検証ジョブを本番ジョブから分離します。

キャッシュとプリインストール：再現性の境界

Ruby、Node.js、Python、Homebrew、OpenSSLの版が変わると、インストールスクリプト、ロックファイル、コンパイル引数が壊れる場合があります。特にキャッシュキーがOSやCPUを含まない場合、新しい環境へ古い成果物を戻して、原因を隠すことがあります。

GitHubの依存関係キャッシュ文書を基準に、キャッシュの保存対象と復元条件を確認します。復旧時はキャッシュなしで一度ビルドし、成功後に新しいキーでキャッシュを作る順序が安全です。プリインストール済みツールを前提にせず、必要な版をワークフローでインストールまたは検証してください。

署名とシミュレーター：ビルド成功後の別障害

通常のコンパイルが通っても、アーカイブ署名、キーチェーン、シミュレーター起動は別の失敗層です。署名失敗では証明書の種類、プロビジョニングプロファイル、キーチェーンのロック状態、xcodebuild archive の完全なログを確認します。秘密情報は必ず ${{ secrets.SIGNING_CERTIFICATE }} のようなプレースホルダーにし、証明書やパスワードをログへ出さないでください。

シミュレーターの失敗では、要求するランタイムがイメージに存在するか、宛先のUDIDが有効か、ヘッドレス実行で必要な権限があるかを調べます。修正後は、コンパイルだけでなく、テスト、アーカイブ、署名済み成果物の検査まで再実行します。

復旧タイムライン：固定タグからリモートMacへ

短期復旧と恒久対策を同じ変更にしないでください。まず検証済みの固定タグで既存ジョブを戻し、その後にXcodeやOSを更新する専用ジョブを作ります。GitHub-hosted runnerの選択肢は、公式Runner文書で現在の提供条件を確認してください。

時点 実施すること 合格条件
障害発生直後 成功・失敗ログとコミット差分を保存 環境差分の有無を説明できる
切り分け段階 CPU、Xcode、SDK、キャッシュを個別に検証 原因候補を1層に絞れる
暫定復旧 検証済みrunnerタグと明示的Xcodeを使用 クリーンビルドが成功する
恒久対策 更新用ジョブと本番ジョブを分離 更新を先に検知できる
移行評価 隔離したリモートMac自前Runnerで再現 再起動後も同じ工程が通る

次の表で、運用条件を比較してください。

条件 固定タグのGitHub-hosted runner リモートMac自前Runner
短期の無状態ジョブ 向いています 準備負担が大きくなります
固定Xcodeと永続キャッシュ 制御範囲を確認する必要があります 管理しやすくなります
私設ネットワークへの接続 組織側の接続設計が必要です ノード側の設計が必要です
署名資産の保持 ジョブごとの安全な注入が中心です キーチェーン管理の責任が増えます
常時稼働プロセス 適性を確認する必要があります 運用しやすい構成です
保守担当 GitHub側と利用者側で分担します OS、Runner、資産を管理します

費用だけでなく、キャッシュの保持、秘密鍵の管理、内製ネットワークへの到達性、障害時の復旧担当まで比較してください。VMSPINの 日本語のMac利用案内 を確認し、実際のワークフローを隔離ノードで試す場合は、必要な接続方式と権限を先に整理します。

最終受け入れでは、次の結果を1枚の記録に残します。

検証項目 記録する内容 不合格時の戻り先
クリーンビルド Xcode、SDK、警告、終了コード Xcode選択と依存関係
キャッシュビルド キー、ヒット条件、生成物のアーキテクチャ キャッシュ分離
テスト シミュレーター名、ランタイム、失敗ログ ランタイムと権限
アーカイブ 署名方式、プロファイル、成果物検査 キーチェーンと署名資産
再起動後の再実行 Runner、サービス、キャッシュ、署名状態 ノードの永続化設計

FAQ

macos-latest の実イメージ確認

macos-latest の実体は、ラベルだけで推測せず、各ジョブの Set up job ログと公式イメージ一覧で確認します。移行告知があった日でも、すべてのジョブが同じ時刻に同じ内容へ変わるとは限りません。成功時のログを保存しておけば、OSやイメージ識別子の差分を具体的に追跡できます。

イメージ変更後のコンパイル失敗

イメージ変更後の失敗では、Xcode、SDK、CPUアーキテクチャ、Homebrewや言語ランタイム、キャッシュ復元結果を順に比較します。コミュニティの報告は再現候補として扱い、一般的な原因とは断定しません。ログで差分を確認できない場合は、コード、ロックファイル、秘密情報の注入も同じ優先度で調べます。

XcodeとCPUの固定方法

検証済みのrunnerタグを指定し、xcode-select でDeveloper Directoryを明示します。さらに uname -m と file でCPUとバイナリを確認し、ARMとIntelの依存キャッシュを分けます。Xcodeの版やSDKはイメージ一覧とAppleの公式文書で利用可能性を確認し、プロジェクトの要求版を検証ジョブで先に試してください。

ARMとIntelの選択

ARMは依存するネイティブバイナリや拡張モジュールが対応し、対象アーキテクチャで再構築できる場合に候補になります。Intel向けの検証済みバイナリやスクリプトが多い場合は、既存環境を固定する方が安全です。判断材料はrunnerラベルではなく、実際のCPU、実行ファイル、パッケージ接頭辞の記録です。

自前Runnerへ移す時期

同じ環境を保ちたいという理由だけで直ちに移行するのではなく、固定Xcode、長期キャッシュ、私設ネットワーク、署名資産、常時稼働処理のいずれが必要かを確認します。該当する項目が多い場合は、VMSPINの 日本語向け利用プラン を確認し、隔離したリモートMacで本番相当のジョブを再起動後まで検証してから判断します。

現在のGitHub-hosted運用は、浮動ラベルの変化、ジョブ間で保持しにくいキャッシュ、私設ネットワークや署名資産の扱い、常時稼働処理との相性が弱点になります。短期障害だけなら固定タグで十分ですが、これらを継続的に管理するなら、VMSPINのリモートMacを検証用ノードとして使い、Xcode、キャッシュ、署名チェーンが再起動後も維持できるかを先に確かめる方が、いきなり本番を置き換えるより安全です。

まずは実際のワークフローを隔離ノードで一巡させ、クリーンビルド、キャッシュビルド、テスト、アーカイブ、再起動後の再実行を記録してください。その結果が合格基準を満たした場合に限り、長期運用のRunner構成へ進むのが堅実です。