2025年12月2日
ソフトウェア
GitHub Actions macos-latest の落とし穴｜macOSバイナリのビルド環境とランタイム互換性の設計
GitHub Actionsの macos-latest は最新OSを指しません。ビルド環境とターゲット環境のバージョン差に起因するmacOSバイナリの互換性問題と、ランナーの明示指定・デプロイメントターゲット設定による解決策を整理します。
概要
macOS向けのバイナリをGitHub Actionsでビルドしている開発現場では、「ローカルでは正常に動作するのに、CI/CDで生成したバイナリが配布先で起動しない」という事象がしばしば報告されます。DigitalBaseでも、社内ツールや配布用CLIのビルドパイプライン整備の過程で同様の問題を確認しました。
本稿では、macos-latest ランナーの実態と、macOS Sequoia（15.x）環境で生じやすいランタイム互換性の問題について、原因と対策を整理します。結論として、macOSのビルドではランナーバージョンとデプロイメントターゲットを明示的に指定する設計が、配布バイナリの安定性確保に有効であると評価しています。
macos-latest は「最新」を指さない
まず前提として押さえておくべき点があります。latest という名称に反し、このタグは必ずしも最新のmacOSバージョンを指しません。
| ランナー名 | 実際のOS |
|---|---|
macos-latest | macOS 14 (Sonoma) |
macos-15 | macOS 15 (Sequoia) |
macos-14 | macOS 14 (Sonoma) |
macos-13 | macOS 13 (Ventura) |
latest は「最新版」ではなく「GitHubが推奨するデフォルト版」を指す名称です。2024年9月にSequoiaがリリースされた後も、macos-latest は長らくSonomaを指し続けていました（2025年12月時点）。この前提を知らずにCI設定を組むと、意図せず1世代前の環境でビルドしてしまうことになります。
なぜ互換性問題が起きるのか
macOSのバイナリは、ビルド時に使用されるXcode／clangのバージョンによって、動作可能な最小OSバージョン（デプロイメントターゲット）が決まります。
- macos-14 ランナー: clang 15系を使用し、macOS 14.0以降をターゲットとする
- macos-15 ランナー: clang 16系以降を使用し、より広い互換性を確保しやすい
ビルド環境とターゲット環境の組み合わせによっては、ランタイムでの互換性問題が発生します。特に厄介なのは、明示的なエラーメッセージを伴わず、プロセスが即座に終了するケースです。原因の切り分けに時間がかかりやすく、CI/CDの安定運用を妨げる要因となります。
確認方法
バイナリの依存関係は otool -L コマンドで確認できます。
otool -L ./your-binary | grep libSystem
libSystem のバージョンから、ビルドに使われた環境をある程度推測できます。
- 1345.x系: macOS 14 (Sonoma)
- 1356.x系: macOS 15 (Sequoia)
配布前にこのコマンドで依存ライブラリのバージョンを確認しておくと、想定外の環境でビルドされていないかを事前に検出できます。
解決策
方法1: ランナーバージョンを明示指定（推奨）
macos-latest ではなく、利用するOSバージョンを明示的に指定します。これにより、GitHub側のデフォルト変更に左右されない再現性の高いビルドが可能になります。
jobs: build-macos: runs-on: macos-15 steps: - uses: actions/checkout@v4 # ... ビルドステップ
方法2: デプロイメントターゲットを指定
macOS 14など、より古い環境もサポートする必要がある場合は、環境変数で下位互換性を持たせます。新しいランナーでビルドしつつ、古いOSでも動作するバイナリを生成できます。
- name: Build env: MACOSX_DEPLOYMENT_TARGET: "14.0" run: | # ビルドコマンド
実運用では、配布対象のOSバージョン分布に応じて方法1と方法2を組み合わせる構成が現実的です。
Linux / Windows との違い
macOSでこの問題が顕在化しやすい背景には、プラットフォームごとのランタイム互換性の設計思想の違いがあります。
| OS | 特徴 |
|---|---|
| Linux | glibcの後方互換性が高く、古い環境でビルドしても新しい環境で動作しやすい |
| Windows | VC++ Runtimeは別途配布が一般的で、OS依存が比較的小さい |
| macOS | libSystemがOSバージョンと密結合しており、互換性問題が起きやすい |
macOSでは libSystem がOSバージョンと密接に結合しているため、ビルド環境とターゲット環境のずれがそのままランタイムの不具合として表面化しやすい点に注意が必要です。
ベストプラクティス
- macOSビルドはバージョンを明示指定する —
macos-latestではなくmacos-15などを使用し、再現性を確保する - リリース前にターゲット環境でテストする — 特にmacOSのメジャーバージョンアップ直後は互換性を必ず検証する
- ワークフローにコメントを残す — なぜそのバージョンを指定しているかを記録し、運用知見をチームに残す
まとめ
macos-latestは最新のmacOSを指すわけではなく、GitHub推奨のデフォルト版を指す- macOSのバイナリ配布では、ビルド環境とターゲット環境のバージョン差に注意が必要である
- Sequoia対応が必要な場合は
macos-15を明示指定する - 互換性問題が疑われる場合は
otool -Lで依存ライブラリを確認する
