GitHub ActionsのセルフホステッドRunnerは、GitHubとの通信にHTTPSの443番ポートを使用します。公式のネットワーク要件を満たしているか確認したうえで、まず「オフライン」「オンラインだがジョブを受け取らない」「ジョブ開始後に失敗」のどれかに分けてください。今週の対応は、症状と直近の成功時刻を記録し、該当する原因だけを調べることです。ラベル不一致なら設定を直し、Macホスト自体が維持できない場合に限って実行環境の変更を検討します。
対象となるのは、GitHub ActionsのmacOS自托管Runnerを保守するエンジニア、iOSビルドの待機が続く開発者、Macビルドノードの自主管理を見直すチームです。
症状からネットワーク、ラベル、launchd、ログへ絞り込み、設定の問題とホストの問題を分けて判断できます。
GitHub Actions macOS Runnerのオフラインとジョブ失敗は別の症状です
GitHub Actionsでは、Runnerの接続状態とワークフローの実行状態を一緒に扱わないことが重要です。GitHubの説明ではRunnerの状態は「Idle」「Active」「Offline」の3種類に分かれます。Offlineは接続状態の問題を示しますが、ジョブがキューに残る場合や開始後に失敗する場合は、別の原因を調べる必要があります。Runnerの状態とトラブルシューティングを参照し、リポジトリまたは組織で表示されている状態と照合してください。
macOSの自托管Runnerがofflineと表示された場合、何から確認しますか?
まずMacが起動してネットワークに接続されているか、Runnerアプリまたはサービスが動いているかを確認します。ホストが稼働していてもGitHubへ接続できなければ、管理画面ではOfflineになることがあります。状態だけでアプリの故障と決めつけず、直近の成功時刻と、その後のOS再起動やネットワーク変更も記録してください。
原因を絞る際は、少なくとも次の3点を別々に確認します。
- ホストの可用性: Macがスリープ、シャットダウン、再起動待ちになっていないか。
- Runnerの稼働: アプリまたはサービスが起動しており、異常終了していないか。
- GitHubへの通信: DNS、ファイアウォール、プロキシ、TLS証明書の状態に問題がないか。
公式の接続確認手順とRunner診断ログを使い、接続先への到達性とエラー時刻を照合してください。TLS検証を無効にする方法は、証明書やプロキシの根本原因を隠すため、通常の修復策として使わないでください。
オンラインで待機する場合はラベルとRunnerグループを比べます
Runnerがオンラインでも、ジョブの条件に一致する空きRunnerが見つからなければ、タスクはキューに残ります。ワークフローのruns-onに指定したラベルと、Runner側のラベルが合っているかを確認し、組織でRunnerグループを使っている場合は、そのグループへのアクセス権も照合します。
GitHub Actionsのルーティングでは、複数のラベルを指定したジョブは、その条件に合うRunnerに割り当てられます。セルフホステッドRunnerのルーティング規則を確認し、実際のワークフローとRunner設定にある値を比べてください。ラベル名のわずかな違い、想定しているグループへの登録漏れ、リポジトリに対するグループのアクセス制限があると、Macが稼働中でも割り当て対象にならないことがあります。
| 症状 | 先に比べる項目 | 判定と次の対応 |
|---|---|---|
| RunnerがOffline | Macの稼働、Runnerプロセス、GitHubへの通信 | ホストか接続の問題を調べ、診断ログの時刻と照合します |
| Runnerはオンラインだが待機 | runs-onのラベル、Runnerのラベル、Runnerグループ |
条件と権限が一致しなければYAMLまたはグループ設定を修正します |
| ジョブ開始後に失敗 | ワークフローログ、Runner診断ログ、ビルドスクリプト | 受け取り後の工程に絞り、依存関係・権限・プロジェクト環境を調べます |
オンラインのmacOS Runnerがジョブを受け取らない場合、Macを交換すべきですか?
先にラベルとRunnerグループを確認します。ワークフローでRunnerを指定する方法に沿ってruns-onを見直し、グループを利用しているならRunnerグループのアクセス設定も確認してください。条件や権限の不一致なら、ホストを変えても直りません。
Runnerがオンラインであることは、ビルドジョブの条件に合っていることや、ジョブを正常に完了できることを保証しません。状態、割り当て条件、実行結果を別々に記録すると、誤ったホスト交換を避けられます。
再起動後に切れるならlaunchdのサービス状態を確認します
macOS Runner排障では、ターミナルから手動で起動できたことと、再起動後もサービスが動き続けることを区別してください。対話セッションでの成功は、launchdによる自動起動や実行ユーザーの権限が正常だという証明にはなりません。
macOS上のGitHub Actions Runnerでlaunchdサービスを調べるには?
Runnerのインストールディレクトリで、公式のサービス管理スクリプトを使って状態を確認します。GitHubのmacOS Runnerサービス設定を参照し、サービスの状態、起動ユーザー、サービスログを照合してください。ログインユーザーとサービスの実行ユーザーが異なる場合、環境変数、ファイル権限、キーチェーンへのアクセスなどが手動起動時と変わることがあります。
確認は次の順で進めます。
- Runnerのインストールディレクトリへ移動し、公式手順にあるサービス状態確認コマンドを実行します。
- 停止中なら、起動スクリプトの結果とエラー出力を保存します。
- launchd側の登録状態とRunnerのサービスログを確認し、起動失敗の時刻を記録します。
- 実行ユーザーが、作業ディレクトリや必要な開発ツールへアクセスできるか確認します。
- 再起動後にサービスが維持され、管理画面でオンラインに戻るかを確かめます。
同じRunnerを手動起動とサービス起動で交互に動かすと、既存プロセスの有無や実行ユーザーの違いが原因を見えにくくします。状態を記録してから停止・再起動を行い、手動起動が成功しただけで恒久的に直ったと判断しないでください。
ネットワーク障害と実行中の失敗はログで分けます
Runnerのネットワーク接続に失敗したとき、どのログを見ますか?
まずGitHub管理画面のRunner診断ログと、Mac上のRunnerインストールディレクトリにある診断情報を、同じ時刻で照合します。HTTPSの443番ポートへの通信、名前解決、プロキシ設定、証明書エラーが見つかった場合は、ネットワークまたは管理ポリシー側へ切り分けます。Runnerの公式トラブルシューティング手順に従い、接続テストの結果とログを合わせて判断してください。
ジョブがRunnerに割り当てられた後の失敗は、接続問題とは限りません。ワークフロー実行画面の各ステップとRunner診断ログを同じ時刻で突き合わせ、Runnerがジョブを受け取る前の障害か、スクリプト実行後の障害かを分けます。ワークフロー実行ログの確認方法では、失敗したステップや出力の確認方法を案内しています。追加情報が必要な場合は、デバッグログの有効化手順を使い、必要な再実行で詳細を採取してください。
ビルド開始後に失敗しているなら、依存関係の取得、署名やファイルへの権限、環境変数、プロジェクトのビルド設定を順に確認します。特定のMac構成が原因だと決めつける前に、実際のエラーと現在のRunner・開発ツールの互換性を公式資料で確かめてください。
修復するか、ホストを見直すかをチェックリストで決めます
設定を直して再発が止まる問題と、ホストの可用性を変えなければ解消しにくい問題は分けて考えます。次の項目を確認し、該当する原因に対してだけ対応してください。
- [ ] RunnerがOfflineなら、Macの起動状態とRunnerプロセスを確認した。
- [ ] GitHubへの通信を確認し、443番ポート、DNS、プロキシ、TLS関連のエラーをログと照合した。
- [ ] Runnerがオンラインで待機するなら、
runs-onとRunnerのラベル、グループのアクセス権を比較した。 - [ ] 再起動後に失われるなら、launchdサービスの状態、実行ユーザー、サービスログを確認した。
- [ ] ジョブ開始後の失敗なら、ワークフローの失敗ステップとRunner診断ログを同じ時刻で比較した。
- [ ] 原因が設定不一致なら設定を修正し、主機の停止や保守負担が原因なら実行環境の変更を評価した。
Macホストが原因なら運用方式を見直します
自主管理のMacは、電源やスリープの管理、OS更新、ネットワーク維持、サービス監視をチーム側で担う必要があります。反対に、リモートMacへ移行しても、runs-onのラベルやRunnerグループの誤設定、ビルドスクリプトの不具合は自動では直りません。まず原因がホストの継続稼働や保守能力にあると確認できた場合に、東京のMac環境の案内と利用料金を確認し、プロジェクトの稼働時間や運用要件と照らして検討してください。
ラベルや権限の修正で解決するなら、現在のRunnerを維持するのが合理的です。一方、Macが頻繁に停止する、サービスを安定して維持できない、保守作業がチームの負担になっている場合は、継続稼働を前提としたリモートMacを選択肢に加えられます。物理ポートへの直接接続や、長期にわたる固定負荷を優先するなら、自前のMacが適する場合もあります。GitHub Actions macOS Runnerのオフライン問題を症状とログで切り分け、主機の問題が確認できたときだけ移行を判断してください。
関連記事
専有のMacで、セルフホスト型CI環境を見直しませんか
VPSPullなら、Apple Silicon搭載の専有物理Macをセルフホスト型CI Runnerの実行環境としてご利用いただけます。
