今週の対応方針は、GitHub Actionsのセルフホスト型Mac Runnerが再起動後にオフラインなら、ホストの到達性、Runnerサービス、GitHubへの通信、ジョブ条件の順に切り分けることです。証拠がない段階でRunnerを削除・再登録せず、実際のワークフローで復旧を確認してから本番のジョブを戻します。

GitHub ActionsのRunnerを管理するプラットフォームエンジニア向けです。
企業Mac CIの障害切り分けと復旧判定を整えたいIT責任者、iOS/macOSのリリース担当者にも役立ちます。

01

GitHub Actionsのセルフホスト型Mac Runnerが再起動後にオフラインなら、まずホストとサービスを分ける

GitHubのOffline表示は、Macの停止、Runnerアプリの停止、GitHubと通信できない状態など、異なる原因で発生します。表示だけを根拠にRunner登録の破損と決めつけず、Macへ接続できるか、Runnerが動いているかを別々に確認します。GitHubのRunner状態と排障手順でも、複数の原因を区別して調べるよう案内されています。

確認結果 切り分ける故障域 次に行うこと
Macへ接続できず、起動の記録も確認できない 電源、起動、ホストの管理経路 現地または運用担当の記録を照合する
Macには接続できるがRunnerが見当たらない Runnerサービスまたはプロセス サービス状態と起動ログを確認する
MacとRunnerは動いているがGitHubはOffline GitHubへの通信 DNS、プロキシ、TLS、診断ログを調べる
GitHubではOnlineだがジョブが待機中 ジョブの振り分け条件 ラベル、Runner group、アクセス権を照合する

確認時は、GitHubのRunner画面、Macへのリモート接続結果、再起動前後の運用記録を並べます。遠隔接続が切れただけなのか、Mac自体が起動していないのかを分ければ、ネットワーク障害をRunner登録の問題として扱う誤りを避けられます。

  • [ ] GitHubのRunner画面でOfflineかOnlineかを確認する
  • [ ] Macへ接続できるか、起動状況を運用記録と照合する
  • [ ] Mac上でRunnerのサービスとプロセスを確認する
  • [ ] 原因を特定する前にRunnerを削除しない
02

Macが起動している場合は、サービス構成とログイン条件を照合する

Macへ接続できても、再起動後にRunnerサービスが起動したとは限りません。Runnerがサービスとして構成されているか、サービス状態とGitHubの表示が一致するかを確認します。GitHubのmacOS向けサービス構成手順に沿って、インストール状態と起動状態を調べてください。

macOSのLaunchAgentはユーザーの実行環境に、LaunchDaemonはシステム側の実行環境に関係します。ユーザーがログインした後だけRunnerが動く構成では、ログインしていない状態でも起動するサービスと同じ前提では運用できません。AppleのService Management資料を参照し、実際の登録先と起動条件を確認します。

見えている状態 確認すること 判断のポイント
Runnerプロセスがない サービスの登録と起動状態 サービス未構成か、起動に失敗したかを分ける
ログイン後にだけ動く LaunchAgentかLaunchDaemonか 無人運転時の起動条件に合っているか
サービスは動作中だがOffline RunnerログとGitHubへの通信 サービス再起動だけで解決すると決めつけない

Runnerのディレクトリで公式手順に沿ってサービス状態を確認し、起動に失敗していればログを保存してから修正します。起動設定を変更した場合は、ログイン状態を変えた条件でもRunnerの状態を見直します。

03

Runnerが動作中なら、通常のインターネット接続とGitHub通信を分けて調べる

MacでWebサイトを開けても、Runnerが必要とするGitHubの接続先へ到達できるとは限りません。DNS、プロキシ、TLS、ファイアウォールの順に確認し、Runnerの診断ログと突き合わせます。セルフホスト型Runnerのプロキシ設定も確認し、端末のプロキシとRunnerが使う設定の差を調べてください。

症状 優先して確認する項目 次の確認
名前解決に失敗する DNS設定と接続先名 端末とRunner実行環境の差を確認する
プロキシ環境で接続できない Runner側のプロキシ設定 設定変更後にRunnerのログを確認する
TLS接続に失敗する 証明書、プロキシによる検査、時刻設定 組織の証明書・通信ポリシーを調べる
原因がログに現れない Runnerの診断ログ 必要に応じてデバッグログを有効にする

診断ログは、GitHubが案内するワークフローのデバッグログ手順に沿って取得します。TLS検証を無効にすることは正式な修復ではありません。ログに通信エラーが残る場合は、ポリシーと証明書の設定を修正してから再確認します。

04

RunnerがOnlineでも、ラベルとグループが合わなければジョブは割り当てられない

RunnerがOnlineなのにワークフローが待機中なら、サービスの再起動ではなく振り分け条件を確認します。runs-onの指定とRunnerのラベルが一致し、対象リポジトリがRunner groupへのアクセスを許可されているかを照合してください。ジョブに使用するRunnerの選択条件、ラベルの管理方法、Runner groupのアクセス制御をそれぞれ確認します。

  • [ ] ワークフローのruns-onが要求するラベルを確認する
  • [ ] Runnerに同じラベルが設定されているか確認する
  • [ ] 対象のRunner groupがリポジトリから利用できるか確認する
  • [ ] 変更後、対象ワークフローがそのRunnerに割り当てられるか見る

よくある確認事項

Macの再起動後にOfflineになる原因は何ですか？
ホストの停止、Runnerサービスの未起動、GitHubへの通信断などが候補です。GitHubの表示だけでは切り分けられないため、ホスト接続とサービス状態から確認します。

macOS上でサービスの起動をどう確かめますか？
Runnerのサービス構成と状態を公式手順で確認します。LaunchAgentとLaunchDaemonでは起動する実行環境が異なるため、ユーザーのログイン後に動くことだけで無人運転時の起動を判断しないでください。

Runnerプロセスが動いているのにOfflineなら何を調べますか？
DNS、プロキシ、TLS、Runnerの診断ログを確認します。一般的なインターネット接続が成功してもRunnerに必要な接続が通るとは限らず、TLS検証を無効にして解決したことにしないでください。

Onlineに戻った後、ジョブが動くことをどう確認しますか？
ラベル、Runner group、リポジトリ権限を照合したうえで、代表的なワークフローを実行します。ジョブの受け付け、必要なツールの呼び出し、結果の返却まで確認してから本番再開を判断します。

05

古い登録やサービス残留は、証拠を確認してから整理する

Runnerが複数表示される、Mac上のサービス名とGitHubの記録が一致しない場合は、旧Runnerの記録、重複サービス、実際の通信断を区別します。サービスの構成や登録を変更する前に、GitHub上のRunner名、Macのサービス状態、現在稼働しているプロセスを記録します。

  • [ ] GitHub上のRunner名と状態を記録する
  • [ ] Mac上のサービス構成と、稼働中のRunnerを照合する
  • [ ] 同じRunner名の重複や旧記録があるか確認する
  • [ ] 登録異常を確認できた場合だけ、公式手順に沿って再構成する

「Offlineだから削除して登録し直す」は標準手順にしません。通信の問題やサービス未起動が原因なら、再登録しても根本原因が残ります。まずサービスと通信を確認し、登録情報に異常があると判断できた場合にだけ再構成します。

06

実ジョブの受け付けから結果返却まで確認して本番へ戻す

Online表示は、ビルドやリリースが復旧した証拠ではありません。最初は本番署名資産に触れない代表的なジョブを使い、Runnerが仕事を受け取り、必要な環境を使い、結果をGitHubへ返せるかを確認します。

  • [ ] Runnerが対象ワークフローを受け付ける
  • [ ] 必要な作業ディレクトリと依存ツールにアクセスできる
  • [ ] ビルドまたは検証処理が完了し、ログと成果物が返る
  • [ ] チームのリリースゲートに照らして本番投入を判断する

問題が残る場合は本番ジョブを戻さず、該当する故障域へ切り戻して調査を続けます。単一の無人Macに依存する運用は、再起動後の遠隔復旧、現地対応、運用担当者の待機が隠れた負担になりやすい一方、Macを購入して専有すれば初期調達や保守の負担が残ります。短期の検証や増設を含めて運用形態を比べるなら、日本向けMacの利用条件と、MESHLAUNCHのリモートMac利用案内で提供内容を確認してください。レンタルは購入や自社運用をすべて置き換えるものではありませんが、必要な期間だけ実機環境を確保したい場合は比較対象になります。