GitHub ActionsセルフホストRunner：2026年Mac構築

Runnerが「Online」でも、再起動後に戻らず、意図しないワークフローまで実行しているなら、まだ本番投入できません。
最短解決策は、管理者権限のあるApple Silicon搭載リモートMacをプライベートリポジトリまたはOrganizationへ登録し、システムサービス化、ラベル振り分け、権限分離、再起動復旧まで検証することです。

この手順を読むべき人

iOSやmacOSプロジェクトに継続的インテグレーション用のMacを追加したい開発者向けです。Organization単位でRunner、ワークフロー、署名情報を管理したいDevOpsエンジニアにも適しています。

GitHubが提供するホスト環境では持続キャッシュ、社内リソースへの接続、固有のAppleツールチェーンに制約がある場合もあります。その場合に、リモートMacをmacOSビルドノードとして長期運用する判断材料を確認できます。

本番Runnerにする前に、何を確認すべきですか？

GitHub ActionsセルフホストRunnerは、Runnerアプリケーションが動作し、GitHub Actionsと通信でき、ワークフローに必要なハードウェア資源を持つホストで利用できます。GitHubは外向きHTTPS接続を443番ポートで確立できること、通信速度の目安として送受信それぞれ70kbps以上を要件として示しています。(GitHub公式のセルフホストRunner要件)

次の項目を、登録前に一つずつ確認してください。

• [ ] Macがスリープや利用者のログアウトで停止しない。
• [ ] Runnerのインストール、サービス登録、ログ確認に使える管理者権限がある。
• [ ] GitHubの宛先へ外向きHTTPS通信ができる。
• [ ] Xcode、Swift、署名ツール、依存パッケージを置く空き容量がある。
• [ ] uname -mでApple Siliconのアーキテクチャを確認できる。
• [ ] ビルド成果物、キャッシュ、ログを保存する場所を決めている。
• [ ] 公開リポジトリの未検証プルリクエストを実行対象から除外できる。

AppleのXcodeシステム要件は、Xcodeの版ごとに対応macOS、SDK、シミュレーター、デバイスサポートが変わります。Xcodeの導入前に、必要なSDKとMacのmacOSをAppleの公式一覧で照合してください。visionOS開発など、一部の用途ではApple Siliconが必要です。(Apple公式のXcodeシステム要件)

リポジトリ単位とOrganization単位はどう選びますか？

単一プロジェクトの試運転なら、まずリポジトリ単位で登録すると影響範囲を限定できます。複数リポジトリで共有する場合はOrganization単位にRunnerグループを作り、対象リポジトリとワークフローを許可する設計に切り替えます。

OrganizationのRunnerグループでは、特定リポジトリだけでなく、特定ワークフローやブランチ、タグ、コミットSHAを指定して利用範囲を絞れます。共有Macを「登録しただけの共通資産」にせず、誰がどのジョブを実行できるかまで設定してください。(GitHub公式のRunnerグループ管理)

第一段階：専用アカウントと隔離範囲を決める

日常開発用のmacOSアカウントとCI用アカウントを分けます。個人のSSH鍵、ブラウザーのログイン状態、Keychain内の開発者情報、作業中のソースコードを同じユーザー環境へ置くと、ビルドスクリプトの誤動作や不審な依存処理が個人データへ到達しやすくなります。

Runnerグループ、作業ディレクトリ、キャッシュ、証明書、App Store Connect用の認証情報を、次のように分けてください。

• 開発用Runner：ビルドとテストのみ。署名鍵は持たせない。
• リリース用Runner：対象リポジトリと承認済みワークフローだけを許可する。
• 一時検証用Runner：外部コードを扱う場合は、永続Runnerではなく破棄前提の環境を優先する。
• 共通キャッシュ：再利用する範囲を決め、秘密情報を保存しない。

GitHubは、セルフホストRunnerが常にクリーンな一時仮想マシンとして動く保証はなく、未信頼コードによって永続的に侵害される可能性があると説明しています。公開リポジトリではフォークからのプルリクエストを通じてホスト上でコードが実行され得るため、公開リポジトリへの割り当ては原則として避けてください。(GitHub公式の安全なセルフホストRunner利用ガイド)

第二段階：Runnerを登録し、Macのサービスとして常駐させる

GitHub ActionsセルフホストRunnerのダウンロードURL、Runnerの版、登録トークンは固定値を記事や社内メモへ貼り付けないでください。GitHubの対象画面から、その時点で表示されたmacOSかつApple Silicon対応の手順をコピーします。GitHubの公式リリースページも、段階的な配布のため、環境によって取得すべき版が異なる場合があると案内しています。(actions/runner公式リリースページ)

登録は次の順序で進めます。

1．作業ディレクトリを作成する

CI専用アカウントでRunner用ディレクトリを作成し、日常開発のホームディレクトリと混在させません。GitHubの設定画面から生成したダウンロードと展開コマンドだけを実行し、古いパッケージを流用しないでください。

2．configスクリプトを実行する

GitHubが表示する登録先URLと期限付きトークンを使い、Runner名、グループ、ラベルを設定します。登録トークンは自動生成され、GitHubの公式手順では有効時間が1時間とされています。ログ、シェル履歴、チケット本文に残さないようにしてください。(GitHub公式のRunner追加手順)

3．ラベルを付ける

Apple Siliconを明確に指定するなら、標準ラベルに加えて、用途を示すカスタムラベルを付けます。例えば、self-hosted、macOS、ARM64、ios-buildのように、OS、アーキテクチャ、用途を分けて表現します。

GitHubの標準ラベルにはOSとアーキテクチャを示すものがありますが、configスクリプトで手動指定したラベルは、実際のホスト構成とGitHub側では検証されません。そのため、uname -mやsystem_profilerの出力を初回ジョブのログへ保存し、ラベルの自己申告だけに依存しないでください。(GitHub公式のRunnerラベル設定)

4．サービスを登録する

Runnerの登録が完了してから、GitHubが案内するsvc.sh installとsvc.sh startを実行します。macOSではlaunchdを使うサービスとして動作し、SSHセッションを閉じてもRunnerが稼働し続ける状態を作れます。サービス化の具体的なコマンドは、使用中のRunnerパッケージに含まれる公式手順を優先してください。(GitHub公式のRunnerサービス設定)

5．オンライン表示以外を確認する

GitHub画面のOnline表示だけでは不十分です。SSHを切断し、再接続後に./svc.sh statusを確認し、さらにMacを再起動して同じ確認を行います。macOSのサービス状態はlaunchctlでも確認でき、Runnerディレクトリ内の.serviceファイルからサービス名を特定できます。(GitHub公式のRunner監視とトラブルシューティング)

Apple Siliconへジョブを正しく振り分けるには？

ワークフローのruns-onには、Runnerグループとラベルを組み合わせます。次のように、Apple Silicon向けのラベルを複数条件で指定すると、対象条件をすべて満たすRunnerだけが候補になります。

jobs:
  build:
    runs-on:
      - self-hosted
      - macOS
      - ARM64
      - ios-build
    steps:
      - uses: actions/checkout@v4
      - name: Verify host
        run: |
          uname -m
          sw_vers
          xcodebuild -version

実際のラベル名は、GitHub画面でRunnerへ付与した名前と一致させてください。ラベルは大文字と小文字を区別しない仕様ですが、チーム内では表記を統一した方が設定ミスを追跡しやすくなります。

最初の検証では、依存パッケージのインストールや署名をいきなり実行しません。まずホスト名、macOS、CPUアーキテクチャ、Xcodeの版、主要ツールのパスをログへ記録し、Runnerの通信確認とプロジェクトのビルド確認を分離します。

選択判断：どの登録方式から始めますか？

• 単一リポジトリで短期間だけ検証する場合：リポジトリRunnerから開始し、対象リポジトリ以外へアクセスできない状態にします。
• 複数の非公開リポジトリで共有する場合：Organization Runnerと専用Runnerグループを使い、対象リポジトリを選択します。
• 署名やリリースを実行する場合：通常ビルド用Runnerと分離し、許可するワークフローを限定します。
• 公開リポジトリのプルリクエストを処理する場合：持続Runnerへ直接送らず、GitHubホスト環境や破棄前提の隔離環境へ戻します。

この判断を先に行うと、後からRunnerを移動してワークフローの権限を修正する作業を減らせます。Runnerグループでは、リポジトリだけでなく、ワークフロー単位で利用範囲を制限する設計も可能です。

署名情報と作業ディレクトリはどう固めますか？

永続Runnerでは、前のジョブが残したファイルやキャッシュが次のジョブへ影響する可能性があります。ジョブ終了後に作業ディレクトリを削除するのか、依存キャッシュだけを残すのか、成果物の保管先をどこにするのかを決めてください。

証明書、プロビジョニングプロファイル、APIキー、トークンはリポジトリへ保存せず、GitHubのSecretsやEnvironment保護、macOS Keychainなど、用途に応じた最小権限の保管方法を選びます。署名ジョブは承認済みブランチからだけ起動し、制御されたテストで署名、成果物のアップロード、ログのマスキングを確認します。

Xcodeの移行や版ごとの互換性は、今回のRunner導入とは別の変更管理として扱います。Appleのシステム要件で対象Xcode、macOS、SDKを確認し、更新前に現在のビルド成果物と失敗時の戻し先を記録してください。

長期運用で、何を定期確認しますか？

GitHub ActionsのRunnerアプリケーションは、ジョブ割り当て時、またはジョブがない場合でもリリース後1週間以内に自動更新される仕様です。ただし、Runner更新とmacOS、Xcode、依存ライブラリの更新を同じ変更として扱うと、失敗原因を切り分けにくくなります。

運用開始後は、次の確認を定期化してください。

• [ ] GitHub上のオンライン状態とビジー状態を確認する。
• [ ] ジョブ待ち時間と失敗率を記録する。
• [ ] ディスク容量、DerivedData、依存キャッシュ、成果物を整理する。
• [ ] svc.sh statusとlaunchdのログを確認する。
• [ ] Runnerアプリケーションの更新状態を確認する。
• [ ] macOSやXcodeの更新前に保守時間と切り戻し方法を決める。
• [ ] 失敗ジョブの再実行が同じ汚染環境を使わないか確認する。
• [ ] Runnerを停止、登録解除、再登録する手順を文書化する。

最終受け入れは「ビルドが一度通った」ではなく、再起動後の復旧、失敗ジョブの再実行、ディスク整理、ノード停止の4項目で判断します。macOSビルドノードを複数運用する場合は、Runner名、ラベル、グループ、許可ワークフロー、保守担当者を一覧化すると、誤ったジョブ振り分けを発見しやすくなります。

運用前に、リモートMacの開発環境構成とMacレンタルの料金プランも確認しておくと、必要な稼働期間と管理範囲を決めやすくなります。

よくある疑問

リモートMacにRunnerを登録したのにOnlineになりません

登録先URL、トークンの有効性、Mac側のサービス状態、外向き443番ポートを順番に確認します。サービスが起動していても、DNSやファイアウォールでGitHubへの接続が遮断されていればジョブは受け取れません。

Xcodeの署名ジョブだけ失敗する場合はどうしますか？

Runnerの通信とXcode署名を別々に検証します。証明書、プロビジョニングプロファイル、Keychainのロック状態、許可ブランチ、App Store Connect用認証情報を確認し、まず署名なしのビルドが成功するかを見てから、制御されたブランチで署名を追加します。

リモートMacを複数プロジェクトで共有できますか？

Organization RunnerとRunnerグループを使えば可能です。ただし、同じMacへ異なる信頼レベルのワークフローを混在させると、作業ファイルや認証情報の境界が曖昧になります。ビルド専用、署名専用、検証専用に分ける方が安全です。

Apple Siliconのラベルだけで実機を保証できますか？

保証できません。ラベルはルーティング条件であり、手動で付与したラベルが実際のCPU構成と一致するかを自動検証するものではありません。初回ジョブでuname -mを出力し、期待するアーキテクチャと一致することを確認してください。

永続Runnerでキャッシュを使うとビルドは速くなりますか？

キャッシュの再利用でダウンロード量を減らせる場合はありますが、速度向上を保証するものではありません。古い依存物や秘密情報が残るリスクもあるため、キャッシュ対象、保存期間、削除条件を先に決め、再現性を壊す共有キャッシュは避けてください。

リモートMacとMac miniのどちらを選ぶべきですか？

長期にわたり同じ負荷をかけ、物理接続や専用ネットワークが必要なら自前のMac miniが適しています。一方、短期のリリース、検証期間、チーム増員、複数構成の試験では、購入、設置、保守、障害復旧を自分で抱えないリモートMacの方が導入しやすい場合があります。

自前のMac miniは、初期購入、設置場所、電源、ネットワーク、OS更新、故障時の交換を自分で管理しなければなりません。Linuxや一般的なクラウド環境へ逃がす方法もありますが、Xcode、Apple SDK、署名、Apple Silicon依存の検証を置き換えられない場合は、長期の代替策になりにくいです。

そのため、まずは管理者権限を持ち、長時間オンラインにできるApple SiliconのMacを確保し、この記事の再起動復旧と署名検証まで実施してください。購入と自己保守を避けたいなら、KVMFLUXのMacレンタル提供内容と利用期間を確認したうえで、必要な期間だけリモートMacを構築環境として使う方法が現実的です。