GitHub公式仕様では、runs-on に指定したラベルをすべて備えるRunnerがジョブの割り当て対象になります。ラベルを使ったルーティングの条件を確認し、オンライン状態とリポジトリのアクセス権も調べてください。原因が供給不足だと確かめられた場合に限り、セルフホストのmacOS Runnerを検討します。追加のマシンだけでは、設定の不一致や権限不足は解消しません。
今週は、まず失敗した実行の記録を保存し、ラベル、稼働状態、アクセス権を順に照合してください。次に、小さなテスト用ワークフローで接続、構築、清掃、復旧を確かめます。
この記事は、GitHub ActionsでiOSまたはmacOSのビルドを運用する開発者向けです。
セルフホストRunnerを導入するチームは、実ジョブでの受け入れ条件を整理できます。
Runnerの保守担当者は、監視と復旧の確認項目を運用手順に加えられます。
キュー待ちと実行失敗は、まず状態で切り分ける
キューに残っている状態、Runnerが仕事を受け取らない状態、ジョブ開始後にビルドが失敗する状態は、原因も調べる場所も異なります。最初に実行記録のURLやジョブ識別情報、失敗時のログを保存し、どの段階で止まったかを記録します。
- ジョブがキューに残る： 要求ラベルに一致するRunnerが利用可能か、対象のRunnerグループにアクセスできるかを確認します。
- Runnerが仕事を受け取らない： Runnerのオンライン表示、サービスの稼働、通信状態を確認します。
- ジョブ開始後に失敗する： ツールチェーン、依存関係、署名、秘密情報を調べます。
GitHub Actionsのデバッグログ設定は、通常のログだけで原因が判断しにくい場合に使います。調査前に実行記録を残せば、後からRunnerの割り当て問題とビルドエラーを混同しにくくなります。
ラベルと権限が合わない場合は、マシンを増やす前に直す
ワークフローのruns-onに指定した条件と、Runnerに割り当てられたラベルが一致しているかを確認します。OS名や独自ラベルを追加している場合は、表記の違い、不要な条件、ラベルの付け忘れにも注意してください。ワークフローからRunnerを選ぶルールに照らして、ジョブの指定と登録内容を一つずつ比べます。
ラベルが合っていても、対象リポジトリにRunnerまたはRunnerグループの利用が許可されていなければ、ジョブを処理できないことがあります。Runnerグループのアクセス設定と安全上の注意を確認し、登録範囲と利用対象を照合してください。マシンが起動していることと、ワークフローから利用できることは別の確認事項です。
第一段階：最小ワークフローで接続を確かめる
機密情報や本番リリース処理を含まないテスト用ワークフローを用意します。対象Runnerを指定し、ジョブが開始されるか、想定したRunnerで実行されたかをログで確認してください。テストが割り当てられないなら、ビルド環境の調整や台数追加ではなく、先にラベルとアクセス範囲を見直します。
オンライン表示と実際の稼働は分けて検証する
Runnerがオフラインの場合は、プロセスやサービスの状態に加え、GitHub Actionsとの通信が保たれているかを調べます。オンライン表示でも、再起動後にサービスが戻らない、短時間の接続断から復旧しないといった問題は、別途確認が必要です。
セルフホストRunnerの監視とトラブルシューティングを参考に、停止や接続断をどう検知し、誰に知らせるかを決めます。復旧確認は画面表示だけで終わらせず、テストジョブが再びRunnerに割り当てられるところまで行います。
macOS環境を用意するときは、使うXcodeの要件と実行環境の対応も確認してください。AppleのXcodeシステム要件は、Xcodeを利用できるmacOS環境を照合するための一次情報です。移行先でOSやツールチェーンの組み合わせが変わる場合、単にRunnerがオンラインになっただけでは、従来どおりビルドできるとは限りません。
起動後の失敗は、スケジューリング障害と分けて調べる
ジョブが始まった後に失敗するなら、まずログ上の失敗地点を確認します。Xcodeのバージョン、依存パッケージの取得先、署名に使う証明書やプロファイル、必要な秘密情報の設定を順番に調べてください。
失敗を「Runnerが足りない」と判断して台数を増やしても、ツールチェーンの不一致や依存先への接続エラーは直りません。キュー待ちとビルド失敗を別の項目として記録し、それぞれに担当する確認手順を用意します。署名情報を扱う場合は、ジョブが参照できる範囲と、終了後に残らないことも確認対象です。
タスク終了後の残留物は、正常終了と異常終了の両方で調べる
作業ディレクトリや一時ファイルの処理を確認するときは、ジョブが成功した場合だけでなく、失敗やキャンセル後も確かめます。特に、署名用ファイルや秘密情報を作業領域へ書き出す構成では、終了後の削除と認証情報の無効化を確認してください。
キャッシュはビルド時間を短縮できる一方、別のワークフローや利用者に見せてはいけないファイルまで共有すると、情報漏えいにつながるおそれがあります。どの内容を再利用するかを限定し、秘密情報や署名素材をキャッシュ対象に含めないようにします。ワークフロー間で同じ作業環境を共有する設計なら、実行後に残るデータとアクセス範囲も検収してください。
受け入れチェックリスト
- [ ] 対象ジョブの要求ラベルとRunnerのラベルが一致している。
- [ ] 対象リポジトリまたは組織からRunnerを利用できる。
- [ ] 最小のテストワークフローがRunnerに割り当てられ、完了する。
- [ ] Xcode、依存関係、署名処理を含む必要な構築を確認した。
- [ ] Runnerの停止や接続断を検知し、復旧後のテスト実行まで確認した。
- [ ] 正常終了、失敗、キャンセル後に作業ファイルや認証情報が残らない。
- [ ] キャッシュの内容と、ワークフロー間の分離条件を確認した。
FAQ：障害の切り分けと移行検収
セルフホストのmacOS Runnerは、固定した構築環境を維持したい場合や、利用可能な処理能力を自分で管理したい場合に候補になります。ただし、キュー待ちの原因がラベルや権限なら、設定を直すのが先です。次の判断分岐に沿って、追加のRunnerが必要かを決めてください。
- ラベルまたはアクセス権が不一致なら： 先にワークフロー指定やRunnerグループを修正します。
- Runnerがオフライン、または再起動後に復旧しないなら： 監視、サービス起動、通信を見直します。
- ジョブは実行されるがビルドに失敗するなら： Xcode、依存関係、署名、秘密情報を切り分けます。
- 条件が合い、利用可能なRunnerが足りないと確認できたなら： セルフホスト環境の追加を検討し、受け入れチェックリストを再実行します。
移行後に不具合が出たときは、旧環境と新環境で実行ログ、構築条件、終了後の残留物を比べます。構築結果だけでなく、復旧や清掃まで確かめてから移行完了と判断してください。
環境の調達方法にも、それぞれ運用負担があります。既存の共有環境は専有の構成や制御範囲が要件に合わない場合があり、自前のMacはOS更新、サービス監視、故障対応、認証情報の管理を継続する必要があります。短期間の検証や一時的な構築環境が目的なら、必要な接続方法や運用範囲を先に決め、Hashvpsの環境案内と利用条件でRunnerの接続要件に合うかを確認してください。条件が合えば、Macを購入して保守し続けるより、必要な期間だけHashvpsのMac環境を利用する方が運用負担を抑えられる場合があります。ラベルや権限の不一致が残っているなら、レンタルを決める前にその設定を修正してください。
macOS CIの待ち時間を、HashvpsのクラウドMacで見直しませんか？
Hashvpsなら、ネイティブmacOSを搭載したMac mini M4をビルドや自動テストの補助ノードとしてご利用いただけます。
専用リソースと専用IPv4で、ビルドや署名に使う環境を分けて運用できます。