CI/CD

GitHub Actions macOS Runner 2026:リモートMacの設定方法

結論:XcodeまたはmacOSが必要なワークフローで、実行元のブランチやリポジトリを信頼できるなら、リモートMacをGitHub Actions macOS Runnerとして登録できます。先にアクセス範囲とトリガーを絞り、サービス起動後に実際のプロジェクトで検証してください。信頼できない公開リポジトリのPRを、機密情報に触れられるRunnerで実行する運用は避けます。

GitHub Actionsを使ってiOSアプリをmacOS上でビルドしたい個人開発者向けに、登録から動作確認までを説明します。
小規模チームの担当者は、Runnerのアクセス管理やサービス状態、ビルド記録の確認にも活用できます。
すでにリモートMacを利用している場合は、常駐ビルドノードとして使える条件を見極められます。

事前判断:リモートMacをRunnerにする条件を決める

セルフホストRunnerは、登録先のGitHubリポジトリにあるワークフローをMac上で実行する仕組みです。Xcodeを使うiOS・macOSのビルドには適していますが、Macの画面を遠隔操作できることだけでは安全なCI環境とはいえません。先に、何のジョブを、どのコードから実行するかを決めます。

GitHub Actions self-hosted runnerでXcodeのビルドは実行できますか?
macOS環境にXcodeと必要なプロジェクト依存関係が整い、ワークフローがそのRunnerを選択すれば実行できます。GitHubのRunner選択方法とセルフホストRunnerの仕様は、セルフホストRunnerの公式リファレンスで確認できます。

登録範囲は、対象リポジトリだけで使うのか、組織内の複数リポジトリで共有するのかに合わせて選びます。共有範囲を広げるほど管理対象も増えるため、用途が限定されるならリポジトリ単位から始め、追加の利用が必要になった時点で見直すのが安全です。GitHubのRunnerへのアクセス範囲の管理方法も参照してください。

条件に応じて、使い方を選ぶ

  • 信頼できるブランチのビルドに限定できる場合:リモートMacを登録し、対象ブランチを絞ったワークフローから段階的に利用します。
  • 外部コントリビューターのコードが実行される場合:Runnerに機密情報や広い権限を持たせず、実行条件を再設計します。
  • 公開リポジトリで不特定のforkからPRを受け付ける場合:秘密情報や内部リソースにアクセスできる自前Runnerで処理しないでください。GitHubは、公開リポジトリのforkからのPRが自前Runner上で不信頼なコードを実行する危険を説明しています。GitHubのRunner追加時のセキュリティ説明を事前に確認してください。

準備:macOSとXcodeの状態を確かめる

Runnerの登録前に、リモートMacへログインできること、GitHubへの通信ができること、ビルドに使うXcodeが起動できることを確かめます。macOSの対話画面で成功した操作でも、後でサービスとして動かした時に同じ環境変数やキーチェーンが使えるとは限りません。

まず、選択中の開発者ディレクトリを確認します。

xcode-select -p

続けて、コマンドラインからXcodeの情報を取得します。

xcodebuild -version
xcodebuild -list -project "App.xcodeproj"

xcode-select -pで意図した開発者ディレクトリが表示されない場合は、Appleのコマンドラインツール設定に関する説明を参照し、使うXcodeを選択してから再確認します。コマンドラインツールの導入条件は、AppleのXcodeコマンドラインツールのインストール案内で確認できます。

ここで必要なのは、実際のプロジェクトを見つけ、ビルドに使うスキームを特定できることです。プロジェクトや依存関係をまだ取得していない段階で、ビルド成功までを前提にRunner登録へ進まないでください。

登録:対象範囲とラベルを設定する

自分のMacをGitHub Actions Runnerにつなぐには、どこから始めますか?
GitHubで対象リポジトリ、組織、または企業のRunner設定を開き、macOS用Runnerを追加します。画面に表示される手順に従い、MacにRunnerアプリを配置して設定してください。登録範囲は後から変更できる場合もありますが、最初は実際にジョブを実行する範囲に絞るのが無難です。

Runnerの登録時には、GitHubが発行する登録情報を使います。トークンやアカウント情報は例示用の値を実値に置き換える方式で扱い、ブログ、ワークフローログ、公開リポジトリ、共有メモへ貼り付けないでください。登録画面の案内やアプリの設定内容は、GitHubのRunnerアプリ設定とサービス化の手順に従います。

ラベルは、ジョブを意図したMacへ割り当てるために使います。既定のラベルに加えて独自ラベルを設定する場合は、Runner側とワークフロー側の指定を一致させてください。登録後はGitHubのRunner一覧でオンライン状態を確認し、対象外のリポジトリからジョブを送れないことも確かめます。

運用開始前:サービスとして起動し、復旧を試す

ターミナルを開いたままにするだけでは、Macの再起動後もRunnerが稼働する運用になりません。GitHubのmacOS向け手順に従ってRunnerをサービスとして設定し、サービス状態とGitHub上のオンライン表示を両方確認します。

公式手順に含まれるサービス操作の例は次のとおりです。実行場所や権限は、Runnerを配置したディレクトリと公式案内に合わせてください。

sudo ./svc.sh install
sudo ./svc.sh start
sudo ./svc.sh status

停止や削除を行う場合も、同じ案内の手順を使います。サービスとしての実行環境と、ログイン中のデスクトップ環境は別に確認してください。特に署名用証明書、キーチェーン、GUI操作に依存する処理は、バックグラウンドのジョブで自動的に利用できると決めつけず、別途安全な設定と検証が必要です。

状態確認の際は、GitHubのRunner監視とトラブルシューティング案内に沿って、サービスのログとGitHub上のオンライン表示を照合します。リモート操作の入口や画面の確認方法も必要なら、KuzCloudのコンソール案内を参照してください。

リモートMac上のRunnerをオンラインに保つには、何を確認しますか?
RunnerアプリをmacOSサービスとして起動し、サービスの稼働状態とGitHub上の表示を照合します。再起動後にもジョブを受け取れるかを確認し、手動ログインが必要な状態や、画面を開いた時だけ動く状態を常用の前提にしないでください。

接続テスト:信頼できるブランチからXcodeを実行する

最初のジョブは、保護された信頼できるブランチから実行し、Runnerへの割り当て、コード取得、Xcodeコマンドの実行を順に確認します。以下は構成例です。ブランチ名、プロジェクト名、スキーム、承認済みのcheckoutアクション参照を、実際のリポジトリに合わせて置き換えてください。

name: macOS build

on:
  push:
    branches:
      - trusted-branch

permissions:
  contents: read

jobs:
  build:
    runs-on: [self-hosted, macOS]
    steps:
      - uses: actions/checkout@<承認済みの参照>
      - name: Check Xcode project
        run: xcodebuild -list -project "App.xcodeproj"
      - name: Build for simulator
        run: >
          xcodebuild
          -project "App.xcodeproj"
          -scheme "App"
          -sdk iphonesimulator
          -configuration Debug
          CODE_SIGNING_ALLOWED=NO
          build

runs-onには登録済みRunnerのラベルを指定します。GitHubのワークフローでセルフホストRunnerを選択する方法とワークフロー構文および権限の設定を照らし合わせ、最小限の権限から始めてください。

ここではビルド確認と署名・アーカイブ・アップロードを切り分けます。まずログにXcodeの実行結果が残ることを確認し、署名や配布を加えるのは、証明書や秘密情報の保管方法を別途設計してからにします。

受け入れ確認:日常運用に入れる証拠を残す

次の項目を満たしたら、実際のワークフローで使い始められるか判断できます。どれかが未確認なら、リリース用ジョブに広げず、原因が特定できるまで検証段階に留めます。

  • [ ] GitHubのRunner一覧で対象Runnerがオンラインになっている。
  • [ ] 信頼できるブランチのジョブだけが対象Runnerへ割り当てられる。
  • [ ] コード取得とxcodebuildのログを後から追跡できる。
  • [ ] ビルド成果物がプロジェクトの想定と一致する。
  • [ ] サービスの停止・再起動後にRunnerが復帰し、ジョブを受け付ける。
  • [ ] ワークフロー権限、Runnerの共有範囲、保存した認証情報を見直せる担当者が決まっている。

運用開始後は、Runnerアプリとワークフローの更新を確認し、不要になったRunnerをアクセス設定から外してアプリも適切に削除します。個人開発者が管理画面でRunnerの登録や稼働状況を確かめる場合は、KuzCloudの利用案内も確認できます。

手元のPCだけで手動ビルドする方法は、担当者の作業時間に依存し、Macが使えない時にはXcodeのビルドを進められず、ログや成果物の受け渡しも個別管理になりやすい点が弱みです。常時使えるmacOSの実行環境が必要になった段階では、遠隔から利用するMacをRunnerにする方法も選択肢になります。購入せず一時的な検証環境を用意したい場合は、KuzCloudの日本向けプラン案内で利用条件を確認し、実際のワークフローに合うかを判断してください。長期間の高負荷運用や物理インターフェースが必要な作業では、自前のMacを含めて比較するのが適切です。

macOS向けCIに、専用Macという選択肢を

KuzCloudなら、Apple Silicon M4搭載の専用Macをセルフホストランナー用の環境としてご利用いただけます。

物理マシンを専有できるため、macOS向けのビルドやテストに必要なツールを自由に導入できます。